npm - @bananapus/router-terminal-v6 - Versions diffs - 0.0.6 → 0.0.7 - Mend

@bananapus/router-terminal-v6 0.0.6 → 0.0.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (13) hide show

package/README.md +78 -36
package/SKILLS.md +206 -58
package/foundry.toml +1 -0
package/package.json +2 -2
package/slither-ci.config.json +1 -1
package/src/JBRouterTerminal.sol +23 -7
package/src/JBRouterTerminalRegistry.sol +9 -1
package/src/interfaces/IJBRouterTerminal.sol +1 -0
package/src/interfaces/IJBRouterTerminalRegistry.sol +2 -1
package/test/RouterTerminal.t.sol +85 -67
package/test/RouterTerminalRegistry.t.sol +3 -3
package/test/regression/L29_LockTerminalRace.t.sol +93 -0
package/test/regression/L30_CashOutLoopLimit.t.sol +211 -0

package/README.md CHANGED Viewed

@@ -1,6 +1,6 @@
-# nana-router-terminal-v6
+# Juicebox Router Terminal
-A Juicebox terminal that accepts payments in any token, dynamically discovers what token each destination project accepts, and routes the payment there — via direct forwarding, Uniswap swap, JB token cashout, or a combination. Supports both Uniswap V3 and V4 pools, choosing whichever offers better liquidity.
+A Juicebox terminal that accepts payments in any token, dynamically discovers what token each destination project accepts, and routes the payment there -- via direct forwarding, Uniswap swap, JB token cashout, or a combination. Supports both Uniswap V3 and V4 pools, choosing whichever offers better liquidity.
 _If you're having trouble understanding this contract, take a look at the [core protocol contracts](https://github.com/Bananapus/nana-core-v6) and the [documentation](https://docs.juicebox.money/) first. If you have questions, reach out on [Discord](https://discord.com/invite/ErQYmth4dS)._
@@ -8,17 +8,18 @@ _If you're having trouble understanding this contract, take a look at the [core
 | Contract | Description |
 |----------|-------------|
-| `JBRouterTerminal` | Core terminal. Accepts any token via `pay` or `addToBalanceOf`, discovers the destination project's accepted token, and routes there — swapping through Uniswap V3 or V4 pools if needed. Uses TWAP oracle for automatic slippage protection when the caller doesn't provide a quote. |
-| `JBRouterTerminalRegistry` | A proxy terminal that delegates `pay` and `addToBalanceOf` to a per-project or default `JBRouterTerminal` instance. Allows project owners to choose (and lock) which router terminal implementation they use. |
+| `JBRouterTerminal` | Core terminal. Accepts any token via `pay` or `addToBalanceOf`, discovers the destination project's accepted token, and routes there -- swapping through Uniswap V3 or V4 pools if needed, cashing out JB project tokens if the input is a project token, or forwarding directly if the token is already accepted. Uses TWAP oracle (V3) or spot price (V4) for automatic slippage protection when the caller does not provide a quote. Implements `IJBTerminal`, `IJBPermitTerminal`, `IUniswapV3SwapCallback`, and `IUnlockCallback`. |
+| `JBRouterTerminalRegistry` | A proxy terminal that delegates `pay` and `addToBalanceOf` to a per-project or default `JBRouterTerminal` instance. Project owners can choose which router terminal they use, and optionally lock that choice permanently. Implements `IJBTerminal` via `IJBRouterTerminalRegistry`. |
 ## How It Works
 1. A payer calls `pay(projectId, token, amount, ...)` with any token.
-2. The terminal accepts the token (supports ERC-20 approvals and Permit2).
-3. It discovers the destination project's accepted token by querying the directory.
-4. If the input token differs from the accepted token, it converts it — by cashing out JB project tokens, swapping through the best Uniswap V3 or V4 pool across multiple fee tiers, or both.
-5. Slippage protection: the caller can pass a minimum output quote in metadata (`quoteForSwap` key), or the terminal calculates one from the pool's TWAP oracle with dynamic slippage tolerance.
-6. The output tokens are forwarded to the project's primary terminal via `terminal.pay(...)` or `terminal.addToBalanceOf(...)`.
+2. The terminal accepts the token (supports ERC-20 approvals, Permit2, and credit transfers).
+3. If the input is a JB project token (ERC-20 or credits), it recursively cashes out through the source project's terminals until reaching a base token.
+4. It resolves which token the destination project accepts, checking: metadata override (`routeTokenOut`), direct acceptance, NATIVE/WETH equivalence, then dynamic pool discovery across all terminals.
+5. If the resolved token differs from the input, it converts -- wrapping/unwrapping ETH/WETH, or swapping through the best Uniswap V3 or V4 pool.
+6. Slippage protection: the caller can pass a minimum output quote in metadata (`quoteForSwap` key), or the terminal calculates one using TWAP (V3) or spot price (V4) with a dynamic sigmoid slippage tolerance based on estimated price impact.
+7. The output tokens are forwarded to the project's primary terminal via `terminal.pay(...)` or `terminal.addToBalanceOf(...)`.
 ```mermaid
 sequenceDiagram
@@ -39,13 +40,22 @@ sequenceDiagram
 ### Routing Strategies
-The terminal can route payments via multiple strategies:
+The terminal uses a multi-step routing algorithm:
-- **Direct forwarding** — If the input token is already accepted by the destination terminal.
-- **Uniswap V3 swap** — Through the highest-liquidity V3 pool across fee tiers (0.01%, 0.05%, 0.3%, 1%).
-- **Uniswap V4 swap** — Through V4 pools, also searching multiple fee/tick-spacing configurations.
-- **JB token cashout** — Redeeming JB project tokens to get the needed output token.
-- **Combination** — Chaining strategies when no single route works.
+1. **JB token cashout** -- If the input is a JB project token (detected via `TOKENS.projectIdOf()` or the `cashOutSource` metadata key for credits), the terminal recursively cashes out through the source project's cashout terminals. At each step it prioritizes: tokens the destination directly accepts, then other JB tokens (recursable), then any base token.
+2. **Direct forwarding** -- If the (possibly post-cashout) token is already accepted by the destination terminal.
+3. **NATIVE/WETH equivalence** -- If the project accepts NATIVE_TOKEN and the input is WETH (or vice versa), wrap or unwrap.
+4. **Uniswap swap** -- Through the highest-liquidity pool across V3 fee tiers (0.3%, 0.05%, 1%, 0.01%) and V4 fee/tick-spacing pairs. V3 and V4 compete on liquidity; the deeper pool wins.
+5. **Combination** -- Chaining cashout + swap when no single route works.
+### Token Output Resolution Priority
+When deciding what token to convert to, `_resolveTokenOut` follows this order:
+1. **Metadata override** -- Payer specifies `routeTokenOut` in metadata.
+2. **Direct acceptance** -- The destination project accepts `tokenIn` as-is.
+3. **NATIVE/WETH equivalence** -- The project accepts the wrapped/unwrapped form.
+4. **Dynamic discovery** -- Iterate all terminals and accounting contexts for the project, find the accepted token with the deepest Uniswap pool against `tokenIn`.
 ## Install
@@ -93,7 +103,9 @@ Key `foundry.toml` settings:
 - `solc = '0.8.26'`
 - `evm_version = 'cancun'` (required for Uniswap V4's transient storage)
-- `optimizer_runs = 100000000`
+- `optimizer_runs = 200`
+- `fuzz.runs = 4096`
+- `invariant.runs = 1024`, `invariant.depth = 100`
 ## Repository Layout
@@ -104,42 +116,72 @@ nana-router-terminal-v6/
 │   ├── JBRouterTerminalRegistry.sol      # Per-project terminal routing
 │   ├── interfaces/
 │   │   ├── IJBRouterTerminal.sol         # Router terminal interface
-│   │   ├── IJBRouterTerminalRegistry.sol # Registry interface
+│   │   ├── IJBRouterTerminalRegistry.sol # Registry interface (extends IJBTerminal)
 │   │   └── IWETH9.sol                    # WETH wrapper interface
 │   ├── libraries/
-│   │   └── JBSwapLib.sol                 # Swap math and pool discovery
+│   │   └── JBSwapLib.sol                 # Slippage tolerance, impact, and price limit math
 │   └── structs/
-│       └── PoolInfo.sol                  # Pool metadata struct
+│       └── PoolInfo.sol                  # V3/V4 pool metadata struct
 ├── script/
-│   ├── Deploy.s.sol                      # Deployment script
+│   ├── Deploy.s.sol                      # Deployment script (multi-chain)
 │   └── helpers/
 │       └── RouterTerminalDeploymentLib.sol # Deployment address loader
 └── test/
-    ├── RouterTerminal.t.sol              # Terminal tests
-    └── RouterTerminalRegistry.t.sol      # Registry tests
+    ├── RouterTerminal.t.sol              # Unit tests (mocked dependencies)
+    ├── RouterTerminalRegistry.t.sol      # Registry unit tests
+    └── RouterTerminalFork.t.sol          # Fork tests against mainnet Uniswap pools
 ```
 ## Payment Metadata
-The `JBRouterTerminal` accepts encoded `metadata` in its `pay(...)` function. Metadata is decoded using `JBMetadataResolver`:
+The `JBRouterTerminal` accepts encoded `metadata` in its `pay(...)` and `addToBalanceOf(...)` functions. Metadata is decoded using `JBMetadataResolver` with string-based keys:
-```solidity
-(bool exists, bytes memory quote) =
-    JBMetadataResolver.getDataFor(JBMetadataResolver.getId("quoteForSwap"), metadata);
+| Key | Type | Purpose |
+|-----|------|---------|
+| `"quoteForSwap"` | `uint256` | Minimum output amount from the swap. Overrides the automatic TWAP/spot-based quote. |
+| `"permit2"` | `JBSingleAllowance` | Permit2 signature for gasless ERC-20 approvals. |
+| `"routeTokenOut"` | `address` | Force the router to convert to a specific output token instead of auto-discovering. Reverts if the destination project does not accept it. |
+| `"cashOutSource"` | `(uint256 sourceProjectId, uint256 creditAmount)` | Cash out credits from `sourceProjectId`. The payer must have granted `TRANSFER_CREDITS` permission (ID 13) to the router terminal. |
+| `"cashOutMinReclaimed"` | `uint256` | Minimum tokens reclaimed from the first cashout step (slippage protection for cashouts). |
+### Quote Example
-if (exists) {
-    (minAmountOut) = abi.decode(quote, (uint256));
-}
+```solidity
+// Provide a minimum output quote in metadata
+bytes memory metadata = JBMetadataResolver.addToMetadata({
+    originalMetadata: "",
+    id: JBMetadataResolver.getId("quoteForSwap"),
+    data: abi.encode(minAmountOut)
+});
+routerTerminal.pay(projectId, usdc, 1000e6, beneficiary, 0, "swap with quote", metadata);
 ```
-If no quote is provided, the terminal calculates one from the pool's TWAP oracle with a dynamic slippage tolerance based on the estimated price impact of the swap.
+If no `quoteForSwap` is provided, the terminal calculates one automatically:
+- **V3 pools**: TWAP oracle with a configurable window (default 10 minutes, capped by oldest observation). Reverts if no observation history exists.
+- **V4 pools**: Spot tick price (V4 vanilla pools have no built-in TWAP oracle).
+- **Both**: Dynamic sigmoid slippage tolerance based on estimated price impact and pool fee. Range: 2% minimum to 88% maximum ceiling.
+## Supported Chains
+The deployment script supports:
+| Chain | WETH | V3 Factory | V4 PoolManager |
+|-------|------|------------|----------------|
+| Ethereum Mainnet | `0xC02a...6Cc2` | `0x1F98...F984` | `0x0000...8A90` |
+| Optimism | `0x4200...0006` | `0x1F98...F984` | `0x0000...8A90` |
+| Base | `0x4200...0006` | `0x3312...FDfD` | `0x0000...8A90` |
+| Arbitrum | `0x82aF...b1DD` | `0x1F98...F984` | `0x0000...8A90` |
+| + Sepolia testnets for each | | | |
-The terminal also supports Permit2 metadata (key: `"permit2"`) for gasless token approvals.
+Permit2 is deployed at `0x000000000022D473030F116dDEE9F6B43aC78BA3` on all chains.
 ## Risks
-- The terminal never holds a token balance. After every swap, all output tokens are forwarded and leftover input tokens are returned to the payer.
-- Pool discovery is dynamic — the terminal searches V3 and V4 pools at runtime. If pool liquidity changes between discovery and execution, slippage protection prevents losses.
-- TWAP fallback: when no TWAP observations exist, the terminal falls back to the pool's current spot tick rather than reverting.
-- The `receive()` function only accepts ETH from the WETH contract (during unwrap). All other senders revert.
-- Uniswap V4 requires `cancun` EVM version (transient storage opcodes). This terminal will not work on chains without EIP-1153 support.
+- The terminal never holds a token balance between transactions. After every swap, all output tokens are forwarded to the destination terminal, and leftover input tokens from partial fills are returned to the payer.
+- Pool discovery is dynamic -- the terminal searches V3 and V4 pools at runtime. If pool liquidity changes between discovery and execution, slippage protection prevents excessive losses.
+- The `receive()` function accepts ETH from any sender. This is required because ETH arrives from multiple sources: WETH unwraps, cash out reclaims from project terminals, and V4 PoolManager takes. The terminal processes all received ETH within the same transaction.
+- TWAP fallback: V3 pools with no TWAP observation history (`oldestObservation == 0`) will cause the transaction to revert with `JBRouterTerminal_NoObservationHistory()`. V4 uses spot price and does not require observations.
+- Uniswap V4 requires `cancun` EVM version (transient storage opcodes). On chains without EIP-1153 support, the terminal falls back to V3-only routing.
+- Credit cashouts require the payer to grant `TRANSFER_CREDITS` permission (ID 13) to the router terminal address. Without this, credit-based routing will revert.
+- The `_cashOutLoop` recursively cashes out JB project tokens. Deeply nested project token chains (project A's token backed by project B's token backed by project C's token, etc.) will consume more gas per level of recursion.

package/SKILLS.md CHANGED Viewed

@@ -1,101 +1,249 @@
-# nana-router-terminal-v6
+# Juicebox Router Terminal
 ## Purpose
-Accept payments in any ERC-20 token (or native ETH), dynamically discover what token the destination project accepts, and route there — via Uniswap V3/V4 swap, direct forwarding, JB token cashout, or a combination.
+Accept payments in any ERC-20 token (or native ETH), dynamically discover what token the destination project accepts, and route there -- via Uniswap V3/V4 swap, direct forwarding, JB token cashout, or a combination. The router terminal also supports credit-based cashouts where a payer transfers their JB project credits to the terminal for cashout and re-routing.
 ## Contracts
 | Contract | Role |
 |----------|------|
-| `JBRouterTerminal` | Core terminal: accepts any token, discovers the best route to the destination project's accepted token, swaps via Uniswap V3 or V4, forwards to primary terminal. Implements `IJBTerminal`, `IJBPermitTerminal`, `IUniswapV3SwapCallback`, `IUnlockCallback`. |
-| `JBRouterTerminalRegistry` | Proxy terminal routing `pay`/`addToBalanceOf` to a per-project or default `JBRouterTerminal`. Implements `IJBTerminal`. |
+| `JBRouterTerminal` | Core terminal: accepts any token, discovers the best route to the destination project's accepted token, swaps via Uniswap V3 or V4, cashes out JB project tokens, forwards to the primary terminal. Implements `IJBTerminal`, `IJBPermitTerminal`, `IUniswapV3SwapCallback`, `IUnlockCallback`, `IJBRouterTerminal`. |
+| `JBRouterTerminalRegistry` | Proxy terminal routing `pay`/`addToBalanceOf` to a per-project or default `JBRouterTerminal`. Project owners can set and lock their terminal choice. Implements `IJBTerminal` via `IJBRouterTerminalRegistry`. |
 ## Key Functions
-| Function | Contract | What it does |
-|----------|----------|--------------|
-| `pay(projectId, token, amount, beneficiary, minReturnedTokens, memo, metadata)` | `JBRouterTerminal` | Accept any token, discover destination's accepted token, swap if needed via best V3/V4 pool, forward to project's primary terminal. Returns project token count. |
-| `addToBalanceOf(projectId, token, amount, shouldReturnHeldFees, memo, metadata)` | `JBRouterTerminal` | Same routing flow but calls `terminal.addToBalanceOf(...)` instead of `terminal.pay(...)`. |
-| `discoverPool(normalizedTokenIn, normalizedTokenOut)` | `JBRouterTerminal` | Search V3 factory for highest liquidity pool across 4 fee tiers (0.01%, 0.05%, 0.3%, 1%). |
-| `discoverBestPool(normalizedTokenIn, normalizedTokenOut)` | `JBRouterTerminal` | Discover best pool across both V3 and V4, comparing liquidity. Returns `PoolInfo` with version, key, and liquidity. |
-| `setTerminalFor(projectId, terminal)` | `JBRouterTerminalRegistry` | Route a project to a specific allowed router terminal. Requires `SET_ROUTER_TERMINAL` permission. |
-| `lockTerminalFor(projectId)` | `JBRouterTerminalRegistry` | Lock the terminal choice for a project (irreversible). |
-| `allowTerminal(terminal)` | `JBRouterTerminalRegistry` | Owner-only: add a terminal to the allowlist. |
-| `setDefaultTerminal(terminal)` | `JBRouterTerminalRegistry` | Owner-only: set the default terminal for projects without a custom choice. |
+### JBRouterTerminal
+| Function | What it does |
+|----------|--------------|
+| `pay(projectId, token, amount, beneficiary, minReturnedTokens, memo, metadata)` | Accept any token, route to the destination project's accepted token (cashout, swap, wrap/unwrap, or direct), forward to the project's primary terminal. Returns project token count. |
+| `addToBalanceOf(projectId, token, amount, shouldReturnHeldFees, memo, metadata)` | Same routing flow as `pay` but calls `terminal.addToBalanceOf(...)` instead of `terminal.pay(...)`. |
+| `discoverPool(normalizedTokenIn, normalizedTokenOut) -> IUniswapV3Pool` | Search V3 factory for highest-liquidity pool across 4 fee tiers. Returns the V3 pool (or zero address if V4 was better). |
+| `discoverBestPool(normalizedTokenIn, normalizedTokenOut) -> PoolInfo` | Discover best pool across both V3 and V4, comparing in-range liquidity. Returns `PoolInfo` indicating protocol version and pool details. |
+| `accountingContextForTokenOf(projectId, token) -> JBAccountingContext` | Returns a dynamically constructed context with 18 decimals and currency = `uint32(uint160(token))`. Does not read from storage. |
+| `accountingContextsOf(projectId) -> JBAccountingContext[]` | Always returns an empty array (this terminal accepts any token dynamically). |
+| `currentSurplusOf(...) -> uint256` | Always returns 0. This terminal holds no surplus. |
+| `uniswapV3SwapCallback(amount0Delta, amount1Delta, data)` | V3 swap callback. Verifies caller is a legitimate pool via the factory. Wraps ETH if needed and transfers input tokens to the pool. |
+| `unlockCallback(data) -> bytes` | V4 swap callback. Called by PoolManager during `unlock()`. Executes the swap, settles input, takes output, checks slippage. |
+| `supportsInterface(interfaceId) -> bool` | Returns true for `IJBTerminal`, `IJBPermitTerminal`, `IERC165`, `IJBPermissioned`. |
+### JBRouterTerminalRegistry
+| Function | What it does |
+|----------|--------------|
+| `pay(projectId, token, amount, beneficiary, minReturnedTokens, memo, metadata)` | Resolves the terminal for the project (per-project or default), accepts funds, forwards payment. |
+| `addToBalanceOf(projectId, token, amount, shouldReturnHeldFees, memo, metadata)` | Same resolution and forwarding but for balance additions. |
+| `terminalOf(projectId) -> IJBTerminal` | Returns the terminal for the project, or `defaultTerminal` if none is set. |
+| `setTerminalFor(projectId, terminal)` | Route a project to a specific allowed router terminal. Requires `SET_ROUTER_TERMINAL` permission (ID 28). Reverts if locked or terminal not allowed. |
+| `lockTerminalFor(projectId, expectedTerminal)` | Lock the terminal choice permanently. If no terminal is explicitly set, the current default is snapshotted. Reverts with `TerminalMismatch` if the resolved terminal does not match `expectedTerminal` (prevents race conditions). Requires `SET_ROUTER_TERMINAL` permission. |
+| `allowTerminal(terminal)` | Owner-only: add a terminal to the allowlist. |
+| `disallowTerminal(terminal)` | Owner-only: remove a terminal from the allowlist. Also clears `defaultTerminal` if it matches. |
+| `setDefaultTerminal(terminal)` | Owner-only: set the default terminal and auto-allow it. |
+| `accountingContextForTokenOf(projectId, token)` | Delegates to the resolved terminal. |
+| `accountingContextsOf(projectId)` | Delegates to the resolved terminal. |
+| `currentSurplusOf(...)` | Always returns 0 (empty implementation). |
+| `supportsInterface(interfaceId) -> bool` | Returns true for `IJBRouterTerminalRegistry`, `IJBTerminal`, `IERC165`. |
+## Internal Routing Functions (JBRouterTerminal)
+| Function | What it does |
+|----------|--------------|
+| `_route(destProjectId, tokenIn, amount, metadata)` | Core routing logic. Detects JB project tokens, runs `_cashOutLoop` if needed, then resolves output token and converts. |
+| `_resolveTokenOut(projectId, tokenIn, metadata)` | Priority: 1) `routeTokenOut` metadata override, 2) direct acceptance, 3) NATIVE/WETH equivalence, 4) `_discoverAcceptedToken`. |
+| `_discoverAcceptedToken(projectId, tokenIn)` | Iterates all terminals and their accounting contexts for a project. Finds the accepted token with the deepest Uniswap pool. Falls back to the first accepted token if no pool exists. |
+| `_convert(tokenIn, tokenOut, amount, projectId, metadata)` | No-op if same token, wrap/unwrap for NATIVE/WETH, or swap via `_handleSwap`. |
+| `_handleSwap(projectId, tokenIn, tokenOut, amount, metadata)` | Discovers the best pool, gets a quote, executes the swap (V3 or V4), unwraps output if needed, returns leftover input to payer. |
+| `_pickPoolAndQuote(metadata, normalizedTokenIn, amount, normalizedTokenOut)` | Discovers pool, checks for user-provided `quoteForSwap`, otherwise computes TWAP quote (V3) or spot quote (V4) with dynamic slippage. |
+| `_cashOutLoop(destProjectId, token, amount, sourceProjectIdOverride, metadata)` | Recursively cashes out JB project tokens. At each step, checks if the destination accepts the reclaimed token. Continues until a non-JB base token is reached or the destination accepts. |
+| `_findCashOutPath(sourceProjectId, destProjectId)` | Priority: 1) tokens the destination directly accepts, 2) JB project tokens (recursable), 3) any base token. Only considers terminals that support `IJBCashOutTerminal`. |
+| `_getSlippageTolerance(amountIn, liquidity, tokenOut, tokenIn, tick, poolFeeBps)` | Computes sigmoid slippage from `JBSwapLib.calculateImpact` and `JBSwapLib.getSlippageTolerance`. |
+| `_bestPoolLiquidity(tokenA, tokenB)` | Scans all V3 fee tiers and V4 pools for the highest in-range liquidity. |
 ## Integration Points
 | Dependency | Import | Used For |
 |------------|--------|----------|
-| `nana-core-v6` | `IJBDirectory`, `IJBTerminal`, `IJBProjects`, `IJBPermissions`, `IJBTokens` | Directory lookups (`primaryTerminalOf`), project ownership, permission checks, token discovery |
-| `nana-core-v6` | `JBMetadataResolver` | Parsing `quoteForSwap` and `permit2` metadata from calldata |
+| `nana-core-v6` | `IJBDirectory`, `IJBTerminal`, `IJBCashOutTerminal`, `IJBProjects`, `IJBPermissions`, `IJBTokens` | Directory lookups (`primaryTerminalOf`, `terminalsOf`), project ownership, permission checks, token discovery, cashout execution |
+| `nana-core-v6` | `JBMetadataResolver` | Parsing `quoteForSwap`, `permit2`, `routeTokenOut`, `cashOutSource`, and `cashOutMinReclaimed` metadata from calldata |
 | `nana-core-v6` | `JBAccountingContext`, `JBSingleAllowance` | Token accounting and Permit2 allowance structs |
-| `nana-permission-ids-v6` | `JBPermissionIds` | Permission ID constants (`SET_ROUTER_TERMINAL`) |
-| `@uniswap/v3-core` | `IUniswapV3Pool`, `IUniswapV3Factory`, `TickMath` | V3 pool swaps, factory pool discovery, tick math |
+| `nana-core-v6` | `IJBPermitTerminal` | Interface for Permit2 support and the `Permit2AllowanceFailed` event |
+| `nana-permission-ids-v6` | `JBPermissionIds` | Permission ID constants: `SET_ROUTER_TERMINAL` (28), `TRANSFER_CREDITS` (13, required by payer for credit cashouts) |
+| `@uniswap/v3-core` | `IUniswapV3Pool`, `IUniswapV3Factory`, `IUniswapV3SwapCallback`, `TickMath` | V3 pool swaps, factory pool discovery, tick math |
 | `@uniswap/v3-periphery` | `OracleLibrary` | TWAP oracle consultation (`consult`, `getQuoteAtTick`, `getOldestObservationSecondsAgo`) |
-| `@uniswap/v4-core` | `IPoolManager`, `PoolKey`, `Currency`, `StateLibrary` | V4 pool swaps and liquidity queries |
+| `@uniswap/v4-core` | `IPoolManager`, `IUnlockCallback`, `PoolKey`, `PoolId`, `Currency`, `BalanceDelta`, `SwapParams`, `StateLibrary` | V4 pool swaps, liquidity queries, settle/take flow |
 | `@uniswap/permit2` | `IPermit2`, `IAllowanceTransfer` | Gasless token approvals |
-| `@openzeppelin/contracts` | `Ownable`, `ERC2771Context`, `SafeERC20` | Access control, meta-transactions, safe transfers |
+| `@openzeppelin/contracts` | `Ownable`, `ERC2771Context`, `SafeERC20`, `Math` | Access control, meta-transactions, safe transfers, sqrt |
+| `@prb/math` | `mulDiv` | Safe fixed-point multiplication in JBSwapLib |
 ## Key Types
-| Struct/Enum | Key Fields | Used In |
-|-------------|------------|---------|
-| `PoolInfo` | `isV4`, `v3Pool`, `v4Key`, `liquidity` | Returned by `discoverBestPool`. Indicates whether the best route is V3 or V4 and stores the pool details. |
-| `JBAccountingContext` | `token`, `decimals`, `currency` | Token accounting contexts for accepted tokens. |
-| `JBSingleAllowance` | `sigDeadline`, `amount`, `expiration`, `nonce`, `signature` | Decoded from `permit2` metadata key for gasless approvals. |
+| Struct | Fields | Used In |
+|--------|--------|---------|
+| `PoolInfo` | `bool isV4`, `IUniswapV3Pool v3Pool`, `PoolKey v4Key` | Returned by `discoverBestPool` and used internally by `_discoverPool`, `_pickPoolAndQuote`. Indicates whether the best route is V3 or V4 and stores the pool reference. |
+| `JBAccountingContext` | `address token`, `uint8 decimals`, `uint32 currency` | Token accounting contexts for accepted tokens. The router terminal constructs these dynamically with 18 decimals. |
+| `JBSingleAllowance` | `uint48 sigDeadline`, `uint160 amount`, `uint48 expiration`, `uint48 nonce`, `bytes signature` | Decoded from `permit2` metadata key for gasless approvals. |
 ## Constants
+### JBRouterTerminal
+| Constant | Value | Purpose |
+|----------|-------|---------|
+| `DEFAULT_TWAP_WINDOW` | `10 minutes` (600 seconds) | Default TWAP oracle window for V3 pool quotes |
+| `SLIPPAGE_DENOMINATOR` | `10,000` | Basis points denominator for slippage tolerance |
+| `_FEE_TIERS` | `[3000, 500, 10000, 100]` | V3 fee tiers to search (0.3%, 0.05%, 1%, 0.01%) |
+| `_V4_FEES` | `[3000, 500, 10000, 100]` | V4 fee tiers to search |
+| `_V4_TICK_SPACINGS` | `[60, 10, 200, 1]` | V4 tick spacings paired with fee tiers |
+### JBSwapLib
 | Constant | Value | Purpose |
 |----------|-------|---------|
-| `DEFAULT_TWAP_WINDOW` | `10 minutes` | Default TWAP oracle window for auto-discovered pools |
-| `FEE_TIERS` | `[3000, 500, 10000, 100]` | V3 fee tiers to search (0.3%, 0.05%, 1%, 0.01%) |
-| `V4_FEES` | `[3000, 500, 10000, 100]` | V4 fee tiers to search |
-| `V4_TICK_SPACINGS` | `[60, 10, 200, 1]` | V4 tick spacings paired with fee tiers |
-| `SLIPPAGE_DENOMINATOR` | `10,000` | Basis points denominator for slippage |
+| `SLIPPAGE_DENOMINATOR` | `10,000` | Basis points denominator |
+| `MAX_SLIPPAGE` | `8,800` (88%) | Maximum slippage ceiling |
+| `IMPACT_PRECISION` | `1e18` | Precision multiplier for impact calculations |
+| `SIGMOID_K` | `5e16` | K parameter for sigmoid curve |
+## Errors
+### JBRouterTerminal
+| Error | When |
+|-------|------|
+| `JBRouterTerminal_NoRouteFound(uint256 projectId, address tokenIn)` | No accepted token found for the project when iterating all terminals |
+| `JBRouterTerminal_TokenNotAccepted(uint256 projectId, address token)` | The `routeTokenOut` metadata override specifies a token the project does not accept |
+| `JBRouterTerminal_CallerNotPool(address caller)` | V3 swap callback called by an address that is not a legitimate factory pool |
+| `JBRouterTerminal_CallerNotPoolManager(address caller)` | V4 unlock callback called by an address other than the PoolManager |
+| `JBRouterTerminal_SlippageExceeded(uint256 amountOut, uint256 minAmountOut)` | Swap output is below the minimum acceptable amount |
+| `JBRouterTerminal_NoPoolFound(address tokenIn, address tokenOut)` | No V3 or V4 pool exists for the token pair |
+| `JBRouterTerminal_NoCashOutPath(uint256 sourceProjectId, uint256 destProjectId)` | No cashout terminal found for the source project |
+| `JBRouterTerminal_NoMsgValueAllowed(uint256 value)` | `msg.value > 0` when paying with an ERC-20 token or using credit cashout |
+| `JBRouterTerminal_PermitAllowanceNotEnough(uint256 amount, uint256 allowance)` | Permit2 allowance is less than the payment amount |
+| `JBRouterTerminal_NoLiquidity()` | Pool has zero in-range liquidity (TWAP or spot quote would be meaningless) |
+| `JBRouterTerminal_NoObservationHistory()` | V3 pool has no TWAP observation history (`oldestObservation == 0`) |
+| `JBRouterTerminal_AmountOverflow(uint256 amount)` | Amount exceeds `type(uint128).max` (required by `OracleLibrary.getQuoteAtTick`) |
+| `JBRouterTerminal_CashOutLoopLimit()` | Cashout loop exceeded 20 iterations (circular token dependency) |
+### JBRouterTerminalRegistry
+| Error | When |
+|-------|------|
+| `JBRouterTerminalRegistry_NoMsgValueAllowed(uint256 value)` | `msg.value > 0` when paying with an ERC-20 |
+| `JBRouterTerminalRegistry_PermitAllowanceNotEnough(uint256 amount, uint256 allowanceAmount)` | Permit2 allowance is less than the payment amount |
+| `JBRouterTerminalRegistry_TerminalLocked(uint256 projectId)` | Attempting to change terminal after it has been locked |
+| `JBRouterTerminalRegistry_TerminalMismatch(IJBTerminal currentTerminal, IJBTerminal expectedTerminal)` | Resolved terminal does not match the `expectedTerminal` passed to `lockTerminalFor` |
+| `JBRouterTerminalRegistry_TerminalNotAllowed(IJBTerminal terminal)` | Attempting to set a terminal that is not on the allowlist |
+| `JBRouterTerminalRegistry_TerminalNotSet(uint256 projectId)` | Attempting to lock when no terminal is set and no default exists |
+## Events
+### JBRouterTerminal
+| Event | When |
+|-------|------|
+| `Permit2AllowanceFailed(address indexed token, address indexed owner, bytes reason)` | Permit2 allowance call failed (from `IJBPermitTerminal`). Payment continues using fallback transfer. |
+### JBRouterTerminalRegistry
+| Event | When |
+|-------|------|
+| `JBRouterTerminalRegistry_AllowTerminal(IJBTerminal terminal)` | Terminal added to allowlist |
+| `JBRouterTerminalRegistry_DisallowTerminal(IJBTerminal terminal)` | Terminal removed from allowlist |
+| `JBRouterTerminalRegistry_LockTerminal(uint256 projectId)` | Terminal locked for a project |
+| `JBRouterTerminalRegistry_SetDefaultTerminal(IJBTerminal terminal)` | Default terminal updated |
+| `JBRouterTerminalRegistry_SetTerminal(uint256 indexed projectId, IJBTerminal terminal)` | Terminal set for a project |
+## Metadata Keys
+| Key | Encoding | Used In | Purpose |
+|-----|----------|---------|---------|
+| `"quoteForSwap"` | `abi.encode(uint256 minAmountOut)` | `_pickPoolAndQuote` | Caller-provided minimum swap output. Overrides TWAP/spot auto-quote. |
+| `"permit2"` | `abi.encode(JBSingleAllowance)` | `_acceptFundsFor` | Permit2 signature for gasless ERC-20 approval. |
+| `"routeTokenOut"` | `abi.encode(address tokenOut)` | `_resolveTokenOut` | Force the router to convert to a specific output token. |
+| `"cashOutSource"` | `abi.encode(uint256 sourceProjectId, uint256 creditAmount)` | `_acceptFundsFor`, `_route` | Cash out credits from `sourceProjectId`. Payer must grant `TRANSFER_CREDITS` (13) to the router. |
+| `"cashOutMinReclaimed"` | `abi.encode(uint256 minTokensReclaimed)` | `_cashOutLoop` | Minimum tokens reclaimed from first cashout step. |
 ## Gotchas
-- The terminal never holds a token balance. After every swap, all output tokens are forwarded and leftover input tokens are returned to the payer.
-- Unlike the swap terminal which had a fixed `TOKEN_OUT`, the router terminal dynamically discovers what token each project accepts. This makes it a universal entry point.
-- Pool discovery runs at call time — it searches V3 and V4 pools across multiple fee tiers. The best pool (by liquidity) wins. This is gas-intensive but ensures optimal routing.
+- **Dynamic accounting contexts**: `accountingContextsOf()` returns an empty array and `accountingContextForTokenOf()` constructs contexts on the fly with 18 decimals. This is intentional -- the router accepts any token.
+- **No surplus, no migration**: `currentSurplusOf()` always returns 0. `migrateBalanceOf()` always returns 0. The terminal is stateless between transactions.
+- Unlike `JBMultiTerminal` which has a fixed `TOKEN_OUT`, the router terminal dynamically discovers what token each project accepts. This makes it a universal entry point.
+- Pool discovery runs at call time -- it searches V3 and V4 pools across 4 fee tiers each (8 pools total). The best pool (by in-range liquidity) wins. This is gas-intensive but ensures optimal routing.
 - When `tokenIn == NATIVE_TOKEN`, the terminal wraps ETH to WETH before swapping. When the output is `NATIVE_TOKEN`, it unwraps WETH after swapping.
-- The `receive()` function only accepts ETH from the WETH contract (during unwrap). All other senders revert.
-- TWAP fallback: when no observations exist (`oldestObservation == 0`), the terminal falls back to the pool's current spot tick and liquidity rather than reverting.
-- Uniswap V4 requires `cancun` EVM version (transient storage). Chains without EIP-1153 cannot use V4 routing — the terminal falls back to V3.
-- The `JBRouterTerminalRegistry` handles token custody during delegation — it transfers tokens from the payer to itself, then to the underlying terminal.
-- Metadata keys: `"quoteForSwap"` for the minimum output amount, `"permit2"` for gasless approvals.
-- `_msgSender()` (ERC-2771) is used instead of `msg.sender` for meta-transaction compatibility.
-- The `JBSwapLib` library contains the core swap execution logic, extracted for contract size management.
+- The `receive()` function accepts ETH from any sender. This is necessary because ETH arrives from WETH unwraps, cashout reclaims from project terminals, and V4 PoolManager takes. The terminal handles all ETH within the same transaction.
+- **V3 TWAP**: Reverts with `JBRouterTerminal_NoObservationHistory()` when a V3 pool has no observation history. The TWAP window is capped by the pool's oldest observation if shorter than 10 minutes.
+- **V4 spot price**: V4 vanilla pools have no built-in TWAP oracle. The terminal uses the current spot tick with the same sigmoid slippage formula.
+- **V4 requires cancun EVM**: Chains without EIP-1153 (transient storage) cannot use V4 routing. If `POOL_MANAGER` is `address(0)`, V4 discovery is skipped entirely.
+- The `JBRouterTerminalRegistry` handles token custody during delegation -- it transfers tokens from the payer to itself, then approves and forwards to the underlying terminal.
+- `_msgSender()` (ERC-2771) is used instead of `msg.sender` for meta-transaction compatibility in both contracts.
+- The `JBSwapLib` library contains slippage tolerance math (sigmoid formula), price impact estimation, and V3-compatible `sqrtPriceLimitX96` calculation. It does not contain swap execution logic.
+- **Leftover handling**: After a swap, leftover input tokens (from partial fills where the price limit was hit) are returned to the payer. For native token inputs, any remaining raw ETH is wrapped to WETH first so the leftover check catches it.
+- **Credit cashouts**: When using `cashOutSource` metadata, the payer must have granted `TRANSFER_CREDITS` permission (ID 13) to the router terminal for the source project. The router calls `TOKENS.transferCreditsFrom()` to pull credits.
+- **Cashout loop depth**: The `_cashOutLoop` iterates through JB project token chains with a cap of 20 iterations (`_MAX_CASHOUT_ITERATIONS`). Exceeding this limit reverts with `JBRouterTerminal_CashOutLoopLimit()`.
+- **V3 callback verification**: The `uniswapV3SwapCallback` verifies the caller by reading the pool's `fee()` and checking `FACTORY.getPool()`. This is standard V3 security.
+- **V4 amount overflow**: Both `_getV3TwapQuote` and `_getV4SpotQuote` revert if `amount > type(uint128).max` because `OracleLibrary.getQuoteAtTick` requires `uint128`.
+- **Disallowing the default terminal**: `disallowTerminal()` clears `defaultTerminal` if it matches the terminal being disallowed.
+- **Locking snapshots default**: `lockTerminalFor(projectId, expectedTerminal)` snapshots the current `defaultTerminal` into `_terminalOf[projectId]` if no explicit terminal was set, preventing future default changes from affecting locked projects. The `expectedTerminal` parameter prevents race conditions where the default changes between transaction submission and execution.
+- **Cashout loop limit**: `_cashOutLoop` is capped at 20 iterations. Circular JB token dependencies (A -> B -> A) will revert with `CashOutLoopLimit` instead of consuming all gas.
 ## Example Integration
 ```solidity
-import {JBRouterTerminal} from "@bananapus/router-terminal-v6/src/JBRouterTerminal.sol";
-import {JBRouterTerminalRegistry} from "@bananapus/router-terminal-v6/src/JBRouterTerminalRegistry.sol";
-// The registry is the entry point for payments.
-// It delegates to per-project or default JBRouterTerminal instances.
-// Pay project 1 with USDC — the router terminal discovers that
-// project 1 accepts ETH, finds the best USDC/WETH pool across
-// V3 and V4, swaps, and forwards ETH to the project's terminal.
-IERC20(usdc).approve(address(registry), 1000e6);
-registry.pay{value: 0}(
+import {IJBTerminal} from "@bananapus/core-v6/src/interfaces/IJBTerminal.sol";
+import {JBMetadataResolver} from "@bananapus/core-v6/src/libraries/JBMetadataResolver.sol";
+import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
+// --- Basic payment (auto-routing, auto-quote) ---
+// Pay project 1 with USDC. The router discovers the project accepts ETH,
+// finds the best USDC/WETH pool across V3 and V4, swaps, and forwards.
+IERC20(usdc).approve(address(routerTerminal), 1000e6);
+routerTerminal.pay(
     1,           // projectId
     usdc,        // token (USDC)
-    1000e6,      // amount (1000 USDC)
+    1000e6,      // amount
     beneficiary, // who receives project tokens
     0,           // minReturnedTokens
-    "Payment via router",
-    ""           // metadata (empty = use TWAP quote)
+    "USDC payment via router",
+    ""           // empty metadata = use auto TWAP/spot quote
 );
-// Project owners can choose a specific router terminal:
-registry.setTerminalFor(projectId, preferredTerminal);
+// --- Payment with explicit quote ---
+bytes memory quoteMetadata = JBMetadataResolver.addToMetadata({
+    originalMetadata: "",
+    id: JBMetadataResolver.getId("quoteForSwap"),
+    data: abi.encode(uint256(0.5 ether)) // minimum 0.5 ETH from swap
+});
-// And lock it permanently:
-registry.lockTerminalFor(projectId);
+IERC20(usdc).approve(address(routerTerminal), 1000e6);
+routerTerminal.pay(
+    1, usdc, 1000e6, beneficiary, 0, "with quote", quoteMetadata
+);
+// --- Payment with explicit output token ---
+bytes memory routeMetadata = JBMetadataResolver.addToMetadata({
+    originalMetadata: "",
+    id: JBMetadataResolver.getId("routeTokenOut"),
+    data: abi.encode(dai) // force conversion to DAI
+});
+IERC20(usdc).approve(address(routerTerminal), 1000e6);
+routerTerminal.pay(
+    1, usdc, 1000e6, beneficiary, 0, "force DAI", routeMetadata
+);
+// --- Native ETH payment ---
+routerTerminal.pay{value: 1 ether}(
+    1,
+    0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE, // NATIVE_TOKEN
+    1 ether,
+    beneficiary,
+    0,
+    "ETH payment",
+    ""
+);
+// --- Registry: project owner sets terminal ---
+registry.setTerminalFor(projectId, preferredTerminal);
+registry.lockTerminalFor(projectId, preferredTerminal); // permanent, reverts if terminal changed
 ```

package/foundry.toml CHANGED Viewed

@@ -6,6 +6,7 @@ libs = ["node_modules", "lib"]
 fs_permissions = [{ access = "read-write", path = "./"}]
 [profile.ci_sizes]
+via_ir = true
 optimizer_runs = 200
 [fuzz]

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/router-terminal-v6",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -17,7 +17,7 @@
     "artifacts": "source ./.env && npx sphinx artifacts --org-id 'ea165b21-7cdc-4d7b-be59-ecdd4c26bee4' --project-name 'nana-router-terminal-v6'"
   },
   "dependencies": {
-    "@bananapus/core-v6": "^0.0.5",
+    "@bananapus/core-v6": "^0.0.9",
     "@openzeppelin/contracts": "^5.2.0",
     "@uniswap/permit2": "github:Uniswap/permit2",
     "@uniswap/v3-core": "github:Uniswap/v3-core#0.8",

package/slither-ci.config.json CHANGED Viewed

@@ -1,5 +1,5 @@
 {
-  "detectors_to_exclude": "timestamp,uninitialized-local,naming-convention,solc-version,shadowing-local",
+  "detectors_to_exclude": "timestamp,uninitialized-local,naming-convention,solc-version,shadowing-local,incorrect-equality",
   "exclude_informational": true,
   "exclude_low": false,
   "exclude_medium": false,

package/src/JBRouterTerminal.sol CHANGED Viewed

@@ -703,6 +703,9 @@ contract JBRouterTerminal is
     {
         address normalizedTokenIn = tokenIn == JBConstants.NATIVE_TOKEN ? address(WETH) : tokenIn;
+        // Snapshot the input token balance before the swap to compute the leftover delta accurately.
+        uint256 balanceBefore = IERC20(normalizedTokenIn).balanceOf(address(this));
         // Execute the swap in a scoped block to manage stack depth.
         amountOut = _executeSwap({
             normalizedTokenIn: normalizedTokenIn,
@@ -721,9 +724,10 @@ contract JBRouterTerminal is
         // Unwrap if output is native token.
         if (tokenOut == JBConstants.NATIVE_TOKEN) WETH.withdraw(amountOut);
-        // Return leftover input tokens to payer.
-        uint256 leftover = IERC20(normalizedTokenIn).balanceOf(address(this));
-        if (leftover != 0) {
+        // Return leftover input tokens to payer using balance delta rather than global balance.
+        uint256 balanceAfter = IERC20(normalizedTokenIn).balanceOf(address(this));
+        if (balanceAfter > balanceBefore) {
+            uint256 leftover = balanceAfter - balanceBefore;
             if (tokenIn == JBConstants.NATIVE_TOKEN) WETH.withdraw(leftover);
             _transferFrom({from: address(this), to: payable(_msgSender()), token: tokenIn, amount: leftover});
         }
@@ -809,7 +813,8 @@ contract JBRouterTerminal is
         address v4In = normalizedTokenIn == address(WETH) ? address(0) : normalizedTokenIn;
         bool zeroForOne = Currency.unwrap(key.currency0) == v4In;
-        uint160 sqrtPriceLimitX96 = zeroForOne ? TickMath.MIN_SQRT_RATIO + 1 : TickMath.MAX_SQRT_RATIO - 1;
+        // Use sqrtPriceLimitFromAmounts for partial-fill protection, consistent with V3 path.
+        uint160 sqrtPriceLimitX96 = JBSwapLib.sqrtPriceLimitFromAmounts(amount, minAmountOut, zeroForOne);
         // V4 sign convention: negative = exact input, positive = exact output.
         bytes memory result =
@@ -1053,6 +1058,7 @@ contract JBRouterTerminal is
             // slither-disable-next-line unused-return,calls-loop
             (uint160 sqrtPriceX96,,,) = POOL_MANAGER.getSlot0(key.toId());
+            // slither-disable-next-line incorrect-equality
             if (sqrtPriceX96 == 0) continue;
             // slither-disable-next-line calls-loop
@@ -1096,6 +1102,10 @@ contract JBRouterTerminal is
         return JBSwapLib.getSlippageTolerance(impact, poolFeeBps);
     }
+    /// @notice The maximum number of cashout iterations before reverting. Prevents infinite loops from circular
+    /// token dependencies.
+    uint256 internal constant _MAX_CASHOUT_ITERATIONS = 20;
     /// @notice Recursively cash out JB project tokens until reaching a token the destination accepts or a base token.
     /// @param destProjectId The ID of the destination project.
     /// @param token The current token being processed.
@@ -1124,7 +1134,7 @@ contract JBRouterTerminal is
             if (exists) minTokensReclaimed = abi.decode(minData, (uint256));
         }
-        while (true) {
+        for (uint256 i; i < _MAX_CASHOUT_ITERATIONS; i++) {
             // Skip the destination check on the first iteration if we have a credit override.
             if (sourceProjectIdOverride == 0) {
                 // slither-disable-next-line calls-loop
@@ -1167,6 +1177,9 @@ contract JBRouterTerminal is
             token = tokenToReclaim;
             sourceProjectIdOverride = 0;
         }
+        // If we reach here, the loop exceeded the maximum iteration count.
+        revert JBRouterTerminal_CashOutLoopLimit();
     }
     /// @notice Find which terminal to cash out from and which token to reclaim.
@@ -1307,11 +1320,14 @@ contract JBRouterTerminal is
             }
         }
+        // Measure balance before transfer to determine actual tokens received (handles fee-on-transfer tokens).
+        uint256 balanceBefore = IERC20(token).balanceOf(address(this));
         // Transfer the tokens from the `_msgSender()` to this terminal.
         _transferFrom({from: _msgSender(), to: payable(address(this)), token: token, amount: amount});
-        // Return the amount transferred.
-        return amount;
+        // Return the actual amount received (balance delta), not the user-supplied amount.
+        return IERC20(token).balanceOf(address(this)) - balanceBefore;
     }
     /// @notice Logic to be triggered before transferring tokens from this terminal.

package/src/JBRouterTerminalRegistry.sol CHANGED Viewed

@@ -35,6 +35,7 @@ contract JBRouterTerminalRegistry is IJBRouterTerminalRegistry, JBPermissioned,
     error JBRouterTerminalRegistry_NoMsgValueAllowed(uint256 value);
     error JBRouterTerminalRegistry_PermitAllowanceNotEnough(uint256 amount, uint256 allowanceAmount);
     error JBRouterTerminalRegistry_TerminalLocked(uint256 projectId);
+    error JBRouterTerminalRegistry_TerminalMismatch(IJBTerminal currentTerminal, IJBTerminal expectedTerminal);
     error JBRouterTerminalRegistry_TerminalNotAllowed(IJBTerminal terminal);
     error JBRouterTerminalRegistry_TerminalNotSet(uint256 projectId);
@@ -265,7 +266,9 @@ contract JBRouterTerminalRegistry is IJBRouterTerminalRegistry, JBPermissioned,
     /// @notice Lock a terminal for a project.
     /// @dev Only the project's owner or an address with the `JBPermissionIds.SET_ROUTER_TERMINAL` permission can lock.
     /// @param projectId The ID of the project to lock the terminal for.
-    function lockTerminalFor(uint256 projectId) external {
+    /// @param expectedTerminal The terminal the caller expects to lock. Prevents race conditions where the default
+    /// changes between transaction submission and execution.
+    function lockTerminalFor(uint256 projectId, IJBTerminal expectedTerminal) external {
         // Enforce permissions.
         _requirePermissionFrom({
             account: PROJECTS.ownerOf(projectId),
@@ -281,6 +284,11 @@ contract JBRouterTerminalRegistry is IJBRouterTerminalRegistry, JBPermissioned,
             _terminalOf[projectId] = terminal;
         }
+        // Verify the resolved terminal matches what the caller expects to lock.
+        if (terminal != expectedTerminal) {
+            revert JBRouterTerminalRegistry_TerminalMismatch(terminal, expectedTerminal);
+        }
         hasLockedTerminal[projectId] = true;
         emit JBRouterTerminalRegistry_LockTerminal(projectId);

package/src/interfaces/IJBRouterTerminal.sol CHANGED Viewed

@@ -18,6 +18,7 @@ interface IJBRouterTerminal {
     error JBRouterTerminal_NoLiquidity();
     error JBRouterTerminal_NoObservationHistory();
     error JBRouterTerminal_AmountOverflow(uint256 amount);
+    error JBRouterTerminal_CashOutLoopLimit();
     /// @notice Search the Uniswap V3 factory for a pool between two tokens across common fee tiers.
     /// @param normalizedTokenIn The input token (wrapped if native).

package/src/interfaces/IJBRouterTerminalRegistry.sol CHANGED Viewed

@@ -49,7 +49,8 @@ interface IJBRouterTerminalRegistry is IJBTerminal {
     /// @notice Lock the terminal for a project, preventing it from being changed.
     /// @param projectId The ID of the project to lock the terminal for.
-    function lockTerminalFor(uint256 projectId) external;
+    /// @param expectedTerminal The terminal the caller expects to lock. Reverts if the current terminal doesn't match.
+    function lockTerminalFor(uint256 projectId, IJBTerminal expectedTerminal) external;
     /// @notice Set the default terminal used when a project has not set a specific terminal.
     /// @param terminal The terminal to set as the default.

package/test/RouterTerminal.t.sol CHANGED Viewed

@@ -30,6 +30,34 @@ import {IJBRouterTerminal} from "../src/interfaces/IJBRouterTerminal.sol";
 import {PoolInfo} from "../src/structs/PoolInfo.sol";
 import {IWETH9} from "../src/interfaces/IWETH9.sol";
+/// @notice Minimal ERC20 mock that tracks balances so balanceOf delta works with L-33's _acceptFundsFor.
+contract MockERC20 {
+    mapping(address => uint256) public balanceOf;
+    mapping(address => mapping(address => uint256)) public allowance;
+    function mint(address to, uint256 amount) external {
+        balanceOf[to] += amount;
+    }
+    function approve(address spender, uint256 amount) external returns (bool) {
+        allowance[msg.sender][spender] = amount;
+        return true;
+    }
+    function transfer(address to, uint256 amount) external returns (bool) {
+        balanceOf[msg.sender] -= amount;
+        balanceOf[to] += amount;
+        return true;
+    }
+    function transferFrom(address from, address to, uint256 amount) external returns (bool) {
+        allowance[from][msg.sender] -= amount;
+        balanceOf[from] -= amount;
+        balanceOf[to] += amount;
+        return true;
+    }
+}
 /// @notice A harness that exposes internal functions for testing.
 contract RouterTerminalHarness is JBRouterTerminal {
     constructor(
@@ -284,13 +312,13 @@ contract RouterTerminalTest is Test {
     function test_pay_directForward() public {
         uint256 projectId = 1;
-        address tokenIn = makeAddr("tokenIn");
+        MockERC20 token = new MockERC20();
+        address tokenIn = address(token);
         uint256 amount = 1000;
         address beneficiary = makeAddr("beneficiary");
         address payer = makeAddr("payer");
         address mockTerminal = makeAddr("destTerminal");
         vm.etch(mockTerminal, hex"00");
-        vm.etch(tokenIn, hex"00");
         // Not a JB token.
         vm.mockCall(address(mockTokens), abi.encodeWithSelector(IJBTokens.projectIdOf.selector), abi.encode(uint256(0)));
@@ -302,16 +330,12 @@ contract RouterTerminalTest is Test {
             abi.encode(mockTerminal)
         );
-        // Mock token transfer from payer.
-        vm.mockCall(tokenIn, abi.encodeCall(IERC20.allowance, (payer, address(routerTerminal))), abi.encode(amount));
-        vm.mockCall(
-            tokenIn, abi.encodeCall(IERC20.transferFrom, (payer, address(routerTerminal), amount)), abi.encode(true)
-        );
+        // Mint tokens to payer and approve the router terminal.
+        token.mint(payer, amount);
+        vm.prank(payer);
+        token.approve(address(routerTerminal), amount);
-        // Mock safeIncreaseAllowance: allowance check + approve.
-        vm.mockCall(
-            tokenIn, abi.encodeCall(IERC20.allowance, (address(routerTerminal), mockTerminal)), abi.encode(uint256(0))
-        );
+        // Mock safeIncreaseAllowance: the router terminal approves the dest terminal.
         vm.mockCall(tokenIn, abi.encodeCall(IERC20.approve, (mockTerminal, amount)), abi.encode(true));
         // Mock dest terminal pay.
@@ -412,12 +436,12 @@ contract RouterTerminalTest is Test {
     function test_addToBalanceOf_directForward() public {
         uint256 projectId = 1;
-        address tokenIn = makeAddr("tokenIn");
+        MockERC20 token = new MockERC20();
+        address tokenIn = address(token);
         uint256 amount = 500;
         address payer = makeAddr("payer");
         address mockTerminal = makeAddr("destTerminal");
         vm.etch(mockTerminal, hex"00");
-        vm.etch(tokenIn, hex"00");
         // Not a JB token.
         vm.mockCall(address(mockTokens), abi.encodeWithSelector(IJBTokens.projectIdOf.selector), abi.encode(uint256(0)));
@@ -429,16 +453,12 @@ contract RouterTerminalTest is Test {
             abi.encode(mockTerminal)
         );
-        // Mock token transfer.
-        vm.mockCall(tokenIn, abi.encodeCall(IERC20.allowance, (payer, address(routerTerminal))), abi.encode(amount));
-        vm.mockCall(
-            tokenIn, abi.encodeCall(IERC20.transferFrom, (payer, address(routerTerminal), amount)), abi.encode(true)
-        );
+        // Mint tokens to payer and approve the router terminal.
+        token.mint(payer, amount);
+        vm.prank(payer);
+        token.approve(address(routerTerminal), amount);
-        // Mock safeIncreaseAllowance.
-        vm.mockCall(
-            tokenIn, abi.encodeCall(IERC20.allowance, (address(routerTerminal), mockTerminal)), abi.encode(uint256(0))
-        );
+        // Mock safeIncreaseAllowance: the router terminal approves the dest terminal.
         vm.mockCall(tokenIn, abi.encodeCall(IERC20.approve, (mockTerminal, amount)), abi.encode(true));
         // Mock dest terminal addToBalanceOf.
@@ -917,49 +937,46 @@ contract RouterTerminalTest is Test {
     /// @notice cashOutMinReclaimed metadata should be forwarded to the cashout terminal (fix #4).
     function test_pay_cashOutMinReclaimedMetadata() public {
-        uint256 destProjectId = 1;
+        MockERC20 jbTokenMock = new MockERC20();
+        address jbToken = address(jbTokenMock);
         address payer = makeAddr("payer");
-        address jbToken = makeAddr("jbToken");
-        vm.etch(jbToken, hex"00");
-        uint256 sourceProjectId = 2;
-        uint256 amount = 100e18;
-        uint256 minReclaimed = 50e18;
         address mockTerminal = makeAddr("destTerminal");
-        vm.etch(mockTerminal, hex"00");
         address mockCashOutTerminal = makeAddr("cashOutTerminal");
+        vm.etch(mockTerminal, hex"00");
         vm.etch(mockCashOutTerminal, hex"00");
         // Build metadata with cashOutMinReclaimed — must use router address for getId.
-        bytes4 metadataId = JBMetadataResolver.getId("cashOutMinReclaimed", address(routerTerminal));
-        bytes memory metadata = JBMetadataResolver.addToMetadata("", metadataId, abi.encode(minReclaimed));
+        bytes memory metadata;
+        {
+            bytes4 metadataId = JBMetadataResolver.getId("cashOutMinReclaimed", address(routerTerminal));
+            metadata = JBMetadataResolver.addToMetadata("", metadataId, abi.encode(uint256(50e18)));
+        }
-        // jbToken is a JB project token for sourceProjectId.
+        // jbToken is a JB project token for sourceProjectId (2).
         vm.mockCall(
-            address(mockTokens), abi.encodeCall(IJBTokens.projectIdOf, (IJBToken(jbToken))), abi.encode(sourceProjectId)
+            address(mockTokens), abi.encodeCall(IJBTokens.projectIdOf, (IJBToken(jbToken))), abi.encode(uint256(2))
         );
-        // Dest project accepts NATIVE_TOKEN.
+        // Dest project (1) accepts NATIVE_TOKEN.
         vm.mockCall(
             address(mockDirectory),
-            abi.encodeCall(IJBDirectory.primaryTerminalOf, (destProjectId, JBConstants.NATIVE_TOKEN)),
+            abi.encodeCall(IJBDirectory.primaryTerminalOf, (1, JBConstants.NATIVE_TOKEN)),
             abi.encode(mockTerminal)
         );
         // Dest project doesn't accept jbToken directly.
         vm.mockCall(
-            address(mockDirectory),
-            abi.encodeCall(IJBDirectory.primaryTerminalOf, (destProjectId, jbToken)),
-            abi.encode(address(0))
+            address(mockDirectory), abi.encodeCall(IJBDirectory.primaryTerminalOf, (1, jbToken)), abi.encode(address(0))
         );
-        // Source project's terminals (for _findCashOutPath).
-        IJBTerminal[] memory sourceTerminals = new IJBTerminal[](1);
-        sourceTerminals[0] = IJBTerminal(mockCashOutTerminal);
-        vm.mockCall(
-            address(mockDirectory),
-            abi.encodeCall(IJBDirectory.terminalsOf, (sourceProjectId)),
-            abi.encode(sourceTerminals)
-        );
+        {
+            // Source project's terminals (for _findCashOutPath).
+            IJBTerminal[] memory sourceTerminals = new IJBTerminal[](1);
+            sourceTerminals[0] = IJBTerminal(mockCashOutTerminal);
+            vm.mockCall(
+                address(mockDirectory), abi.encodeCall(IJBDirectory.terminalsOf, (2)), abi.encode(sourceTerminals)
+            );
+        }
         // Mock supportsInterface for IJBCashOutTerminal.
         vm.mockCall(
@@ -968,52 +985,53 @@ contract RouterTerminalTest is Test {
             abi.encode(true)
         );
-        // Accounting context: source project terminal accepts NATIVE_TOKEN.
-        JBAccountingContext[] memory contexts = new JBAccountingContext[](1);
-        contexts[0] = JBAccountingContext({
-            token: JBConstants.NATIVE_TOKEN, decimals: 18, currency: uint32(uint160(JBConstants.NATIVE_TOKEN))
-        });
-        vm.mockCall(
-            mockCashOutTerminal,
-            abi.encodeCall(IJBTerminal.accountingContextsOf, (sourceProjectId)),
-            abi.encode(contexts)
-        );
+        {
+            // Accounting context: source project terminal accepts NATIVE_TOKEN.
+            JBAccountingContext[] memory contexts = new JBAccountingContext[](1);
+            contexts[0] = JBAccountingContext({
+                token: JBConstants.NATIVE_TOKEN, decimals: 18, currency: uint32(uint160(JBConstants.NATIVE_TOKEN))
+            });
+            vm.mockCall(
+                mockCashOutTerminal, abi.encodeCall(IJBTerminal.accountingContextsOf, (2)), abi.encode(contexts)
+            );
+        }
         // Mock cashOutTokensOf — use broad selector matching since vm.mockCall matches by prefix.
-        // The key assertion: the call should use minReclaimed (not 0).
         vm.mockCall(
             mockCashOutTerminal,
             abi.encodeWithSelector(IJBCashOutTerminal.cashOutTokensOf.selector),
             abi.encode(uint256(60e18))
         );
-        // Expect the specific cashOutTokensOf call with minReclaimed = minReclaimed.
+        // Expect the specific cashOutTokensOf call with minReclaimed = 50e18.
         vm.expectCall(
             mockCashOutTerminal,
             abi.encodeCall(
                 IJBCashOutTerminal.cashOutTokensOf,
                 (
                     address(routerTerminal),
-                    sourceProjectId,
-                    amount,
+                    2, // sourceProjectId
+                    100e18, // amount
                     JBConstants.NATIVE_TOKEN,
-                    minReclaimed,
+                    50e18, // minReclaimed
                     payable(address(routerTerminal)),
                     bytes("")
                 )
             )
         );
-        // Mock token transfer from payer.
-        vm.mockCall(jbToken, abi.encodeCall(IERC20.allowance, (payer, address(routerTerminal))), abi.encode(amount));
-        vm.mockCall(
-            jbToken, abi.encodeCall(IERC20.transferFrom, (payer, address(routerTerminal), amount)), abi.encode(true)
-        );
+        // Mint jbToken to payer and approve the router terminal (L-33: _acceptFundsFor uses balanceOf delta).
+        jbTokenMock.mint(payer, 100e18);
+        vm.prank(payer);
+        jbTokenMock.approve(address(routerTerminal), 100e18);
+        // Fund the router terminal with ETH to cover the cashout reclaim (NATIVE_TOKEN).
+        vm.deal(address(routerTerminal), 60e18);
         // Mock dest terminal pay.
         vm.mockCall(mockTerminal, abi.encodeWithSelector(IJBTerminal.pay.selector), abi.encode(uint256(10)));
         vm.prank(payer);
-        routerTerminal.pay(destProjectId, jbToken, amount, payer, 0, "", metadata);
+        routerTerminal.pay(1, jbToken, 100e18, payer, 0, "", metadata);
     }
 }

package/test/RouterTerminalRegistry.t.sol CHANGED Viewed

@@ -196,7 +196,7 @@ contract RouterTerminalRegistryTest is Test {
         registry.setTerminalFor(projectId, terminalA);
         vm.prank(projectOwner);
-        registry.lockTerminalFor(projectId);
+        registry.lockTerminalFor(projectId, terminalA);
         // Try to change.
         vm.prank(projectOwner);
@@ -231,7 +231,7 @@ contract RouterTerminalRegistryTest is Test {
         );
         vm.prank(projectOwner);
-        registry.lockTerminalFor(projectId);
+        registry.lockTerminalFor(projectId, terminalA);
         assertTrue(registry.hasLockedTerminal(projectId));
         // Should have snapshotted the default as the project's terminal.
@@ -258,7 +258,7 @@ contract RouterTerminalRegistryTest is Test {
         vm.expectRevert(
             abi.encodeWithSelector(JBRouterTerminalRegistry.JBRouterTerminalRegistry_TerminalNotSet.selector, projectId)
         );
-        registry.lockTerminalFor(projectId);
+        registry.lockTerminalFor(projectId, terminalA);
     }
     // ──────────────────────────────────────────────────────────────────────

package/test/regression/L29_LockTerminalRace.t.sol ADDED Viewed

@@ -0,0 +1,93 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.26;
+import {Test} from "forge-std/Test.sol";
+import {IJBPermissions} from "@bananapus/core-v6/src/interfaces/IJBPermissions.sol";
+import {IJBProjects} from "@bananapus/core-v6/src/interfaces/IJBProjects.sol";
+import {IJBTerminal} from "@bananapus/core-v6/src/interfaces/IJBTerminal.sol";
+import {JBPermissionIds} from "@bananapus/permission-ids-v6/src/JBPermissionIds.sol";
+import {IERC721} from "@openzeppelin/contracts/token/ERC721/IERC721.sol";
+import {IPermit2} from "@uniswap/permit2/src/interfaces/IPermit2.sol";
+import {JBRouterTerminalRegistry} from "../../src/JBRouterTerminalRegistry.sol";
+/// @notice Regression test for L-29: lockTerminalFor should revert if current terminal doesn't match expected.
+contract L29_LockTerminalRaceTest is Test {
+    JBRouterTerminalRegistry registry;
+    IJBPermissions permissions = IJBPermissions(makeAddr("permissions"));
+    IJBProjects projects = IJBProjects(makeAddr("projects"));
+    IPermit2 permit2 = IPermit2(makeAddr("permit2"));
+    address owner = makeAddr("owner");
+    address trustedForwarder = makeAddr("trustedForwarder");
+    IJBTerminal terminalA = IJBTerminal(makeAddr("terminalA"));
+    IJBTerminal terminalB = IJBTerminal(makeAddr("terminalB"));
+    uint256 projectId = 1;
+    address projectOwner = makeAddr("projectOwner");
+    function setUp() public {
+        registry = new JBRouterTerminalRegistry(permissions, projects, permit2, owner, trustedForwarder);
+        // Allow both terminals.
+        vm.startPrank(owner);
+        registry.setDefaultTerminal(terminalA);
+        registry.allowTerminal(terminalB);
+        vm.stopPrank();
+        // Mock permissions.
+        vm.mockCall(address(projects), abi.encodeCall(IERC721.ownerOf, (projectId)), abi.encode(projectOwner));
+        vm.mockCall(
+            address(permissions),
+            abi.encodeWithSignature(
+                "hasPermission(address,address,uint256,uint256,bool,bool)",
+                projectOwner,
+                projectOwner,
+                projectId,
+                JBPermissionIds.SET_ROUTER_TERMINAL,
+                true,
+                true
+            ),
+            abi.encode(true)
+        );
+    }
+    /// @notice Locking with the correct expected terminal should succeed.
+    function test_lockTerminalFor_succeedsWithCorrectExpected() public {
+        vm.prank(projectOwner);
+        registry.lockTerminalFor(projectId, terminalA);
+        assertTrue(registry.hasLockedTerminal(projectId));
+    }
+    /// @notice Locking with the wrong expected terminal should revert.
+    function test_lockTerminalFor_revertsWithWrongExpected() public {
+        // Project has no explicit terminal, so it resolves to defaultTerminal (terminalA).
+        // Trying to lock with terminalB should revert.
+        vm.prank(projectOwner);
+        vm.expectRevert(
+            abi.encodeWithSelector(
+                JBRouterTerminalRegistry.JBRouterTerminalRegistry_TerminalMismatch.selector, terminalA, terminalB
+            )
+        );
+        registry.lockTerminalFor(projectId, terminalB);
+    }
+    /// @notice If a project has an explicit terminal set, locking with the wrong one reverts.
+    function test_lockTerminalFor_revertsWhenExplicitTerminalMismatch() public {
+        // Set terminalB for the project.
+        vm.prank(projectOwner);
+        registry.setTerminalFor(projectId, terminalB);
+        // Try to lock expecting terminalA -- should revert.
+        vm.prank(projectOwner);
+        vm.expectRevert(
+            abi.encodeWithSelector(
+                JBRouterTerminalRegistry.JBRouterTerminalRegistry_TerminalMismatch.selector, terminalB, terminalA
+            )
+        );
+        registry.lockTerminalFor(projectId, terminalA);
+    }
+}

package/test/regression/L30_CashOutLoopLimit.t.sol ADDED Viewed

@@ -0,0 +1,211 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.26;
+import {Test} from "forge-std/Test.sol";
+import {IJBCashOutTerminal} from "@bananapus/core-v6/src/interfaces/IJBCashOutTerminal.sol";
+import {IJBDirectory} from "@bananapus/core-v6/src/interfaces/IJBDirectory.sol";
+import {IJBPermissions} from "@bananapus/core-v6/src/interfaces/IJBPermissions.sol";
+import {IJBProjects} from "@bananapus/core-v6/src/interfaces/IJBProjects.sol";
+import {IJBTerminal} from "@bananapus/core-v6/src/interfaces/IJBTerminal.sol";
+import {IJBToken} from "@bananapus/core-v6/src/interfaces/IJBToken.sol";
+import {IJBTokens} from "@bananapus/core-v6/src/interfaces/IJBTokens.sol";
+import {JBConstants} from "@bananapus/core-v6/src/libraries/JBConstants.sol";
+import {JBAccountingContext} from "@bananapus/core-v6/src/structs/JBAccountingContext.sol";
+import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
+import {IERC165} from "@openzeppelin/contracts/utils/introspection/IERC165.sol";
+import {IPermit2} from "@uniswap/permit2/src/interfaces/IPermit2.sol";
+import {IUniswapV3Factory} from "@uniswap/v3-core/contracts/interfaces/IUniswapV3Factory.sol";
+import {IPoolManager} from "@uniswap/v4-core/src/interfaces/IPoolManager.sol";
+import {JBRouterTerminal} from "../../src/JBRouterTerminal.sol";
+import {IJBRouterTerminal} from "../../src/interfaces/IJBRouterTerminal.sol";
+import {IWETH9} from "../../src/interfaces/IWETH9.sol";
+/// @notice Minimal ERC20 mock for balance-delta accounting in _acceptFundsFor (L-33).
+contract MockToken {
+    mapping(address => uint256) public balanceOf;
+    mapping(address => mapping(address => uint256)) public allowance;
+    function mint(address to, uint256 amount) external {
+        balanceOf[to] += amount;
+    }
+    function approve(address spender, uint256 amount) external returns (bool) {
+        allowance[msg.sender][spender] = amount;
+        return true;
+    }
+    function transfer(address to, uint256 amount) external returns (bool) {
+        balanceOf[msg.sender] -= amount;
+        balanceOf[to] += amount;
+        return true;
+    }
+    function transferFrom(address from, address to, uint256 amount) external returns (bool) {
+        allowance[from][msg.sender] -= amount;
+        balanceOf[from] -= amount;
+        balanceOf[to] += amount;
+        return true;
+    }
+}
+/// @notice Regression test for L-30: _cashOutLoop should revert with CashOutLoopLimit when circular token
+/// dependencies cause more than 20 iterations, instead of consuming all gas.
+contract L30_CashOutLoopLimitTest is Test {
+    JBRouterTerminal routerTerminal;
+    IJBDirectory directory = IJBDirectory(makeAddr("directory"));
+    IJBPermissions permissions = IJBPermissions(makeAddr("permissions"));
+    IJBProjects projects = IJBProjects(makeAddr("projects"));
+    IJBTokens tokens = IJBTokens(makeAddr("tokens"));
+    IPermit2 permit2 = IPermit2(makeAddr("permit2"));
+    IWETH9 weth = IWETH9(makeAddr("weth"));
+    IUniswapV3Factory factory = IUniswapV3Factory(makeAddr("factory"));
+    address owner = makeAddr("owner");
+    address payer = makeAddr("payer");
+    address mockTerminal = makeAddr("mockTerminal");
+    // Two JB project tokens that form a cycle: tokenA -> tokenB -> tokenA -> ...
+    MockToken tokenA;
+    MockToken tokenB;
+    uint256 constant DEST_PROJECT_ID = 99;
+    uint256 constant PROJECT_A_ID = 10;
+    uint256 constant PROJECT_B_ID = 20;
+    function setUp() public {
+        vm.etch(address(directory), hex"00");
+        vm.etch(address(permissions), hex"00");
+        vm.etch(address(projects), hex"00");
+        vm.etch(address(tokens), hex"00");
+        vm.etch(address(permit2), hex"00");
+        vm.etch(address(weth), hex"00");
+        vm.etch(address(factory), hex"00");
+        vm.etch(mockTerminal, hex"00");
+        routerTerminal = new JBRouterTerminal(
+            directory,
+            permissions,
+            projects,
+            tokens,
+            permit2,
+            owner,
+            weth,
+            factory,
+            IPoolManager(address(0)), // no V4
+            address(0)
+        );
+        tokenA = new MockToken();
+        tokenB = new MockToken();
+        // tokenA is the JB project token for PROJECT_A_ID.
+        vm.mockCall(
+            address(tokens),
+            abi.encodeCall(IJBTokens.projectIdOf, (IJBToken(address(tokenA)))),
+            abi.encode(PROJECT_A_ID)
+        );
+        // tokenB is the JB project token for PROJECT_B_ID.
+        vm.mockCall(
+            address(tokens),
+            abi.encodeCall(IJBTokens.projectIdOf, (IJBToken(address(tokenB)))),
+            abi.encode(PROJECT_B_ID)
+        );
+        // Destination project does not accept tokenA or tokenB directly.
+        vm.mockCall(
+            address(directory),
+            abi.encodeCall(IJBDirectory.primaryTerminalOf, (DEST_PROJECT_ID, address(tokenA))),
+            abi.encode(address(0))
+        );
+        vm.mockCall(
+            address(directory),
+            abi.encodeCall(IJBDirectory.primaryTerminalOf, (DEST_PROJECT_ID, address(tokenB))),
+            abi.encode(address(0))
+        );
+        // --- Circular cashout path setup ---
+        // Project A's terminal cashes out to tokenB.
+        _setupCashOutTerminal(PROJECT_A_ID, address(tokenB));
+        // Project B's terminal cashes out to tokenA.
+        _setupCashOutTerminal(PROJECT_B_ID, address(tokenA));
+    }
+    function _setupCashOutTerminal(uint256 projectId, address reclaimToken) internal {
+        address terminal = makeAddr(string(abi.encodePacked("terminal", projectId)));
+        vm.etch(terminal, hex"00");
+        // Register as the project's terminal.
+        IJBTerminal[] memory terminalList = new IJBTerminal[](1);
+        terminalList[0] = IJBTerminal(terminal);
+        vm.mockCall(address(directory), abi.encodeCall(IJBDirectory.terminalsOf, (projectId)), abi.encode(terminalList));
+        // Supports IJBCashOutTerminal.
+        vm.mockCall(
+            terminal,
+            abi.encodeCall(IERC165.supportsInterface, (type(IJBCashOutTerminal).interfaceId)),
+            abi.encode(true)
+        );
+        // Accounting context: terminal accepts the reclaim token.
+        JBAccountingContext[] memory contexts = new JBAccountingContext[](1);
+        contexts[0] = JBAccountingContext({token: reclaimToken, decimals: 18, currency: uint32(uint160(reclaimToken))});
+        vm.mockCall(terminal, abi.encodeCall(IJBTerminal.accountingContextsOf, (projectId)), abi.encode(contexts));
+        // cashOutTokensOf returns 1e18 each time (simulating a successful cashout).
+        vm.mockCall(
+            terminal, abi.encodeWithSelector(IJBCashOutTerminal.cashOutTokensOf.selector), abi.encode(uint256(1e18))
+        );
+    }
+    /// @notice A circular cashout chain (A -> B -> A -> ...) must revert with CashOutLoopLimit, not OOG.
+    function test_cashOutLoop_revertsOnCircularDependency() public {
+        uint256 amount = 10e18;
+        // Mint tokenA to payer and approve.
+        tokenA.mint(payer, amount);
+        vm.prank(payer);
+        tokenA.approve(address(routerTerminal), amount);
+        // Expect the specific CashOutLoopLimit revert.
+        vm.expectRevert(abi.encodeWithSelector(IJBRouterTerminal.JBRouterTerminal_CashOutLoopLimit.selector));
+        vm.prank(payer);
+        routerTerminal.pay(DEST_PROJECT_ID, address(tokenA), amount, payer, 0, "", "");
+    }
+    /// @notice A non-circular path within the iteration cap should succeed normally.
+    function test_cashOutLoop_succeedsWithinLimit() public {
+        uint256 amount = 10e18;
+        address baseToken = makeAddr("baseToken");
+        vm.etch(baseToken, hex"00");
+        // Override: tokenB is NOT a JB token (breaks the cycle).
+        vm.mockCall(
+            address(tokens), abi.encodeCall(IJBTokens.projectIdOf, (IJBToken(address(tokenB)))), abi.encode(uint256(0))
+        );
+        // Dest project accepts baseToken via a terminal (so the router can swap tokenB -> baseToken).
+        // For simplicity: dest accepts tokenB directly.
+        vm.mockCall(
+            address(directory),
+            abi.encodeCall(IJBDirectory.primaryTerminalOf, (DEST_PROJECT_ID, address(tokenB))),
+            abi.encode(mockTerminal)
+        );
+        // Mock dest terminal pay.
+        vm.mockCall(mockTerminal, abi.encodeWithSelector(IJBTerminal.pay.selector), abi.encode(uint256(5)));
+        // Mint and approve tokenA.
+        tokenA.mint(payer, amount);
+        vm.prank(payer);
+        tokenA.approve(address(routerTerminal), amount);
+        vm.prank(payer);
+        uint256 result = routerTerminal.pay(DEST_PROJECT_ID, address(tokenA), amount, payer, 0, "", "");
+        assertEq(result, 5);
+    }
+}