@bananapus/router-terminal-v6 0.0.20 → 0.0.21

package/ARCHITECTURE.md

@@ -63,7 +63,7 @@ Payer → JBRouterTerminal.pay(projectId, token, amount)
   │         │
   │         ├─ 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 _resolveRefundTo (checks msg.sender's IJBPayerTracker.originalPayer() via try-catch, falls back to beneficiary/msgSender)
+  │         └─ 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
@@ -104,7 +104,7 @@ terminal source for loan sizing, debt normalization, or any other decimals-depen
 
 **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.
 
-**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 (`_resolveRefundTo`) 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.
+**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.
 
 **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.
 

package/CHANGE_LOG.md

@@ -157,6 +157,13 @@ In v6, when a Permit2 allowance call fails during `_acceptFundsFor()`, an event
 
 ## 3. Event Changes
 
+### 3.0 Indexer Notes
+
+This repo is the direct replacement for v5 swap-terminal indexing:
+- all registry event families moved from `JBSwapTerminalRegistry_*` to `JBRouterTerminalRegistry_*`;
+- registry events now include `caller`;
+- route discovery is dynamic, so do not assume one fixed output token or one manually-registered default pool per project.
+
 ### 3.1 Registry Events Renamed
 All events were renamed from `JBSwapTerminalRegistry_*` to `JBRouterTerminalRegistry_*`.
 

package/RISKS.md

@@ -7,7 +7,7 @@
 - **JBDirectory.** Terminal resolution trusts `DIRECTORY.primaryTerminalOf()` and `DIRECTORY.terminalsOf()`. A compromised directory can redirect funds.
 - **PERMIT2.** Used as fallback for token transfers. Permit2 approvals can be exploited if users have stale allowances.
 - **Owner (Ownable).** Contract owner has no fund access but controls the registry terminal allowlist and default.
-- **`IJBPayerTracker` implementers.** `_resolveRefundTo` in the router terminal queries `IJBPayerTracker(msg.sender).originalPayer()` via try-catch. Any contract that is the `msg.sender` and implements `IJBPayerTracker` can direct leftover refunds to an arbitrary address. This is safe when the caller is a trusted intermediary (e.g. the registry), but a malicious `msg.sender` implementing `IJBPayerTracker` could redirect refunds. The risk is bounded: the caller must have already supplied the funds being routed, so it can only redirect leftovers from its own payment.
+- **`IJBPayerTracker` implementers.** `_resolveRefundWithBackupRecipient` in the router terminal queries `IJBPayerTracker(msg.sender).originalPayer()` via try-catch. Any contract that is the `msg.sender` and implements `IJBPayerTracker` can direct leftover refunds to an arbitrary address. This is safe when the caller is a trusted intermediary (e.g. the registry), but a malicious `msg.sender` implementing `IJBPayerTracker` could redirect refunds. The risk is bounded: the caller must have already supplied the funds being routed, so it can only redirect leftovers from its own payment.
 
 ## 2. Economic / Manipulation Risks
 
@@ -78,7 +78,7 @@ Verified in `RouterTerminalReentrancy.t.sol`: re-entrant calls via both `pay()`
 
 ### 8.2 Router trusts `originalPayer()` from any `msg.sender` that implements it
 
-`_resolveRefundTo` calls `IJBPayerTracker(msg.sender).originalPayer()` in a try-catch. If the call succeeds and returns a non-zero address, leftover tokens from partial swap fills are sent to that address instead of the beneficiary or `_msgSender()`. The router does not verify that `msg.sender` is the registry or any specific contract -- it trusts any caller that implements the interface. This is accepted because: (1) the caller (`msg.sender`) is the entity that supplied the funds, so redirecting its own leftovers is a legitimate operation, (2) if the call reverts or returns `address(0)`, the router falls back to the normal beneficiary/`_msgSender()` logic, and (3) decoupling from the registry allows other intermediary contracts (e.g. batch payers, aggregators) to participate in refund routing without requiring changes to the router terminal.
+`_resolveRefundWithBackupRecipient` calls `IJBPayerTracker(msg.sender).originalPayer()` in a try-catch. If the call succeeds and returns a non-zero address, leftover tokens from partial swap fills are sent to that address instead of the beneficiary or `_msgSender()`. The router does not verify that `msg.sender` is the registry or any specific contract -- it trusts any caller that implements the interface. This is accepted because: (1) the caller (`msg.sender`) is the entity that supplied the funds, so redirecting its own leftovers is a legitimate operation, (2) if the call reverts or returns `address(0)`, the router falls back to the normal beneficiary/`_msgSender()` logic, and (3) decoupling from the registry allows other intermediary contracts (e.g. batch payers, aggregators) to participate in refund routing without requiring changes to the router terminal.
 
 ### 8.3 Cashout loop slippage is first-hop only (accepted trade-off)
 

package/SKILLS.md

@@ -60,7 +60,7 @@ If `tokenIn` is a JB project token, a cashout loop runs first (up to 20 iteratio
 
 ## Routing Architecture
 
-The router uses `_route` (mutative) and `_previewRoute` (view) as the top-level entry points. Both follow the same path: detect JB project tokens and `_cashOutLoop` if needed, then `_resolveTokenOut` to pick the output token, then `_convert` to execute the conversion (no-op, wrap/unwrap, or `_handleSwap`). Swap execution goes through `_pickPoolAndQuote` (discover pool, get TWAP or spot quote with sigmoid slippage), then dispatches to V3 (`uniswapV3SwapCallback`) or V4 (`unlockCallback`). Leftover input tokens from partial fills are returned to the `beneficiary` (for `pay()`) or `_msgSender()` (for `addToBalanceOf()`).
+The router uses `_route` (mutative) and `_previewRoute` (view) as the top-level entry points. Both follow the same path: detect JB project tokens and `_cashOutLoop` if needed, then `_resolveTokenOut` to pick the output token, then `_convert` to execute the conversion (no-op, wrap/unwrap, or `_handleSwap`). Swap execution goes through `_pickPoolAndQuote` (discover pool, get TWAP or spot quote with sigmoid slippage), then dispatches to V3 (`uniswapV3SwapCallback`) or V4 (`unlockCallback`). Leftover input tokens from partial fills are returned via `_resolveRefundWithBackupRecipient`. When the caller (`msg.sender`) implements `IJBPayerTracker` and `originalPayer()` returns a non-zero address, leftovers go to that address. Otherwise, leftovers go to `beneficiary` (for `pay()`) or `_msgSender()` (for `addToBalanceOf()`).
 
 ## Integration Points
 
@@ -201,7 +201,7 @@ The router uses `_route` (mutative) and `_previewRoute` (view) as the top-level
 - 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 via `_resolveRefundTo`. When the caller (`msg.sender`) implements `IJBPayerTracker` and `originalPayer()` returns a non-zero address, leftovers go to that address. Otherwise they go to the `beneficiary` (for `pay()`) or `_msgSender()` (for `addToBalanceOf()`). For native token inputs, any remaining raw ETH is wrapped to WETH first so the leftover check catches it.
+- **Leftover handling**: After a swap, leftover input tokens (from partial fills where the price limit was hit) are returned via `_resolveRefundWithBackupRecipient`. When the caller (`msg.sender`) implements `IJBPayerTracker` and `originalPayer()` returns a non-zero address, leftovers go to that address. Otherwise, leftovers go to `beneficiary` (for `pay()`) or `_msgSender()` (for `addToBalanceOf()`). For native token inputs, any remaining raw ETH is wrapped to WETH first so the leftover check catches it.
 - **`IJBPayerTracker` decoupling**: The router terminal does not import or depend on `IJBRouterTerminalRegistry` for refund resolution. It queries `IJBPayerTracker(msg.sender).originalPayer()` via try-catch. Any intermediary contract that implements `IJBPayerTracker` can forward calls to the router and have leftovers returned to the original payer.
 - **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()`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/router-terminal-v6",
-  "version": "0.0.20",
+  "version": "0.0.21",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -17,8 +17,8 @@
     "artifacts": "source ./.env && npx sphinx artifacts --org-id 'ea165b21-7cdc-4d7b-be59-ecdd4c26bee4' --project-name 'nana-router-terminal-v6'"
   },
   "dependencies": {
-    "@bananapus/address-registry-v6": "^0.0.15",
-    "@bananapus/core-v6": "^0.0.27",
+    "@bananapus/address-registry-v6": "^0.0.16",
+    "@bananapus/core-v6": "^0.0.28",
     "@bananapus/permission-ids-v6": "^0.0.14",
     "@openzeppelin/contracts": "^5.6.1",
     "@uniswap/permit2": "github:Uniswap/permit2",

package/src/JBRouterTerminal.sol

@@ -224,7 +224,7 @@ contract JBRouterTerminal is
             tokenIn: token,
             amount: _acceptFundsFor({token: token, amount: amount, metadata: metadata}),
             metadata: metadata,
-            refundTo: _resolveRefundTo(payable(_msgSender()))
+            refundTo: _resolveRefundWithBackupRecipient(payable(_msgSender()))
         });
 
         uint256 payValue = _beforeTransferFor({to: address(destTerminal), token: token, amount: amount});
@@ -275,7 +275,7 @@ contract JBRouterTerminal is
             tokenIn: token,
             amount: _acceptFundsFor({token: token, amount: amount, metadata: metadata}),
             metadata: metadata,
-            refundTo: _resolveRefundTo(payable(beneficiary))
+            refundTo: _resolveRefundWithBackupRecipient(payable(beneficiary))
         });
 
         uint256 payValue = _beforeTransferFor({to: address(destTerminal), token: token, amount: amount});
@@ -518,7 +518,7 @@ contract JBRouterTerminal is
     /// go to the true payer rather than the intermediary.
     /// @param fallback_ The default refund address to use when no original payer is available.
     /// @return The address to refund partial-fill leftovers to.
-    function _resolveRefundTo(address payable fallback_) internal view returns (address payable) {
+    function _resolveRefundWithBackupRecipient(address payable fallback_) internal view returns (address payable) {
         // Only attempt the call if msg.sender is a contract (EOAs have no code and would revert).
         if (msg.sender.code.length > 0) {
             // Check if the caller implements IJBPayerTracker and has an original payer set.

package/test/audit/LeftoverRefund.t.sol

@@ -0,0 +1,424 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.28;
+
+import {Test} from "forge-std/Test.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 {IJBRulesetApprovalHook} from "@bananapus/core-v6/src/interfaces/IJBRulesetApprovalHook.sol";
+import {IJBTerminal} from "@bananapus/core-v6/src/interfaces/IJBTerminal.sol";
+import {IJBTokens} from "@bananapus/core-v6/src/interfaces/IJBTokens.sol";
+import {JBMetadataResolver} from "@bananapus/core-v6/src/libraries/JBMetadataResolver.sol";
+import {JBAccountingContext} from "@bananapus/core-v6/src/structs/JBAccountingContext.sol";
+import {JBPayHookSpecification} from "@bananapus/core-v6/src/structs/JBPayHookSpecification.sol";
+import {JBRuleset} from "@bananapus/core-v6/src/structs/JBRuleset.sol";
+import {IPermit2} from "@uniswap/permit2/src/interfaces/IPermit2.sol";
+import {IUniswapV3Factory} from "@uniswap/v3-core/contracts/interfaces/IUniswapV3Factory.sol";
+import {IUniswapV3Pool} from "@uniswap/v3-core/contracts/interfaces/IUniswapV3Pool.sol";
+import {IPoolManager} from "@uniswap/v4-core/src/interfaces/IPoolManager.sol";
+
+import {JBRouterTerminal} from "../../src/JBRouterTerminal.sol";
+import {IWETH9} from "../../src/interfaces/IWETH9.sol";
+
+contract AuditLeftoverMockERC20 {
+    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) {
+        uint256 allowed = allowance[from][msg.sender];
+        if (allowed != type(uint256).max) allowance[from][msg.sender] = allowed - amount;
+        balanceOf[from] -= amount;
+        balanceOf[to] += amount;
+        return true;
+    }
+}
+
+contract AuditLeftoverMockWETH is IWETH9 {
+    uint256 public totalSupply;
+    mapping(address => uint256) public balanceOf;
+    mapping(address => mapping(address => uint256)) public allowance;
+
+    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) {
+        uint256 allowed = allowance[from][msg.sender];
+        if (allowed != type(uint256).max) allowance[from][msg.sender] = allowed - amount;
+        balanceOf[from] -= amount;
+        balanceOf[to] += amount;
+        return true;
+    }
+
+    function deposit() external payable override {
+        balanceOf[msg.sender] += msg.value;
+        totalSupply += msg.value;
+    }
+
+    function withdraw(uint256 amount) external override {
+        balanceOf[msg.sender] -= amount;
+        totalSupply -= amount;
+        payable(msg.sender).transfer(amount);
+    }
+
+    receive() external payable {}
+}
+
+contract AuditLeftoverDestTerminal is IJBTerminal {
+    uint256 public lastAmount;
+
+    function addAccountingContextsFor(uint256, JBAccountingContext[] calldata) external override {}
+
+    function addToBalanceOf(
+        uint256,
+        address,
+        uint256 amount,
+        bool,
+        string calldata,
+        bytes calldata
+    )
+        external
+        payable
+        override
+    {
+        lastAmount = amount;
+    }
+
+    function accountingContextForTokenOf(
+        uint256,
+        address token
+    )
+        external
+        pure
+        override
+        returns (JBAccountingContext memory)
+    {
+        return JBAccountingContext({token: token, decimals: 18, currency: uint32(uint160(token))});
+    }
+
+    function accountingContextsOf(uint256) external pure override returns (JBAccountingContext[] memory contexts) {
+        contexts = new JBAccountingContext[](1);
+        contexts[0] = JBAccountingContext({token: address(1), decimals: 18, currency: 1});
+    }
+
+    function currentSurplusOf(uint256, address[] calldata, uint256, uint256) external pure override returns (uint256) {}
+
+    function migrateBalanceOf(uint256, address, IJBTerminal) external pure override returns (uint256) {}
+
+    function pay(
+        uint256,
+        address,
+        uint256 amount,
+        address,
+        uint256,
+        string calldata,
+        bytes calldata
+    )
+        external
+        payable
+        override
+        returns (uint256)
+    {
+        lastAmount = amount;
+        return amount;
+    }
+
+    function previewPayFor(
+        uint256,
+        address,
+        uint256 amount,
+        address,
+        bytes calldata
+    )
+        external
+        pure
+        override
+        returns (JBRuleset memory, uint256, uint256, JBPayHookSpecification[] memory hookSpecifications)
+    {
+        hookSpecifications = new JBPayHookSpecification[](0);
+        return (JBRuleset(0, 0, 0, 0, 0, 0, 0, IJBRulesetApprovalHook(address(0)), 0), amount, 0, hookSpecifications);
+    }
+
+    function supportsInterface(bytes4) external pure override returns (bool) {
+        return true;
+    }
+}
+
+contract AuditLeftoverPartialFillPool is IUniswapV3Pool {
+    address internal immutable _token0;
+    address internal immutable _token1;
+    AuditLeftoverMockERC20 internal immutable _outputToken;
+    uint24 public immutable override fee = 3000;
+    uint128 public immutable override liquidity = 1_000_000;
+
+    uint256 public immutable amountInUsed;
+    uint256 public immutable amountOutGiven;
+
+    constructor(
+        address token0_,
+        address token1_,
+        AuditLeftoverMockERC20 outputToken_,
+        uint256 amountInUsed_,
+        uint256 amountOutGiven_
+    ) {
+        _token0 = token0_;
+        _token1 = token1_;
+        _outputToken = outputToken_;
+        amountInUsed = amountInUsed_;
+        amountOutGiven = amountOutGiven_;
+    }
+
+    function swap(
+        address recipient,
+        bool zeroForOne,
+        int256,
+        uint160,
+        bytes calldata data
+    )
+        external
+        override
+        returns (int256 amount0, int256 amount1)
+    {
+        if (zeroForOne) {
+            JBRouterTerminal(payable(msg.sender))
+                .uniswapV3SwapCallback(int256(amountInUsed), -int256(amountOutGiven), data);
+            _outputToken.mint(recipient, amountOutGiven);
+            return (int256(amountInUsed), -int256(amountOutGiven));
+        }
+
+        JBRouterTerminal(payable(msg.sender)).uniswapV3SwapCallback(-int256(amountOutGiven), int256(amountInUsed), data);
+        _outputToken.mint(recipient, amountOutGiven);
+        return (-int256(amountOutGiven), int256(amountInUsed));
+    }
+
+    function token0() external view override returns (address) {
+        return _token0;
+    }
+
+    function token1() external view override returns (address) {
+        return _token1;
+    }
+
+    function tickSpacing() external pure override returns (int24) {
+        return 1;
+    }
+
+    function slot0() external pure override returns (uint160, int24, uint16, uint16, uint16, uint8, bool) {
+        return (0, 0, 0, 0, 0, 0, false);
+    }
+
+    function feeGrowthGlobal0X128() external pure override returns (uint256) {}
+    function feeGrowthGlobal1X128() external pure override returns (uint256) {}
+    function protocolFees() external pure override returns (uint128, uint128) {}
+    function ticks(int24)
+        external
+        pure
+        override
+        returns (uint128, int128, uint256, uint256, int56, uint160, uint32, bool)
+    {}
+    function tickBitmap(int16) external pure override returns (uint256) {}
+    function positions(bytes32) external pure override returns (uint128, uint256, uint256, uint128, uint128) {}
+    function observations(uint256) external pure override returns (uint32, int56, uint160, bool) {}
+    function observe(uint32[] calldata) external pure override returns (int56[] memory, uint160[] memory) {}
+    function snapshotCumulativesInside(int24, int24) external pure override returns (int56, uint160, uint32) {}
+    function increaseObservationCardinalityNext(uint16) external override {}
+    function mint(address, int24, int24, uint128, bytes calldata) external pure override returns (uint256, uint256) {}
+    function collect(address, int24, int24, uint128, uint128) external pure override returns (uint128, uint128) {}
+    function burn(int24, int24, uint128) external pure override returns (uint256, uint256) {}
+    function flash(address, uint256, uint256, bytes calldata) external override {}
+    function initialize(uint160) external override {}
+    function setFeeProtocol(uint8, uint8) external override {}
+    function collectProtocol(address, uint128, uint128) external pure override returns (uint128, uint128) {}
+
+    function factory() external pure override returns (address) {
+        return address(0);
+    }
+
+    function maxLiquidityPerTick() external pure override returns (uint128) {
+        return type(uint128).max;
+    }
+}
+
+contract LeftoverRefundTest is Test {
+    JBRouterTerminal internal router;
+    IJBDirectory internal directory;
+    IJBPermissions internal permissions;
+    IJBProjects internal projects;
+    IJBTokens internal tokens;
+    IPermit2 internal permit2;
+    IUniswapV3Factory internal factory;
+    IWETH9 internal weth;
+
+    uint256 internal constant PROJECT_ID = 1;
+
+    function setUp() public {
+        directory = IJBDirectory(makeAddr("directory"));
+        permissions = IJBPermissions(makeAddr("permissions"));
+        projects = IJBProjects(makeAddr("projects"));
+        tokens = IJBTokens(makeAddr("tokens"));
+        permit2 = IPermit2(makeAddr("permit2"));
+        factory = IUniswapV3Factory(makeAddr("factory"));
+        weth = IWETH9(address(new AuditLeftoverMockWETH()));
+
+        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(factory), hex"00");
+
+        router = new JBRouterTerminal(
+            directory,
+            permissions,
+            projects,
+            tokens,
+            permit2,
+            makeAddr("owner"),
+            weth,
+            factory,
+            IPoolManager(address(0)),
+            address(0)
+        );
+    }
+
+    /// @notice Partial-fill leftovers from pay() are refunded to the beneficiary.
+    function test_payPartialFillRefundsBeneficiary() public {
+        AuditLeftoverMockERC20 tokenIn = new AuditLeftoverMockERC20();
+        AuditLeftoverMockERC20 tokenOut = new AuditLeftoverMockERC20();
+        AuditLeftoverDestTerminal destTerminal = new AuditLeftoverDestTerminal();
+        AuditLeftoverPartialFillPool pool = _deployPool(tokenIn, tokenOut, 600 ether, 100 ether);
+
+        _mockSimpleSwapRoute(tokenIn, tokenOut, destTerminal, pool);
+
+        address alice = makeAddr("alice");
+        address bob = makeAddr("bob");
+
+        tokenIn.mint(alice, 1000 ether);
+        vm.prank(alice);
+        tokenIn.approve(address(router), type(uint256).max);
+
+        vm.prank(alice);
+        router.pay(PROJECT_ID, address(tokenIn), 1000 ether, bob, 0, "", _metadata(tokenOut));
+
+        assertEq(destTerminal.lastAmount(), 100 ether, "destination only receives filled output");
+        assertEq(tokenIn.balanceOf(bob), 400 ether, "beneficiary receives leftover input");
+        assertEq(tokenIn.balanceOf(alice), 0, "payer receives nothing extra");
+    }
+
+    function test_addToBalanceRefundAlsoLeaksPreexistingRouterBalance() public {
+        AuditLeftoverMockERC20 tokenIn = new AuditLeftoverMockERC20();
+        AuditLeftoverMockERC20 tokenOut = new AuditLeftoverMockERC20();
+        AuditLeftoverDestTerminal destTerminal = new AuditLeftoverDestTerminal();
+        AuditLeftoverPartialFillPool pool = _deployPool(tokenIn, tokenOut, 600 ether, 100 ether);
+
+        _mockSimpleSwapRoute(tokenIn, tokenOut, destTerminal, pool);
+
+        address donor = makeAddr("donor");
+        address attacker = makeAddr("attacker");
+
+        tokenIn.mint(donor, 50 ether);
+        vm.prank(donor);
+        tokenIn.transfer(address(router), 50 ether);
+
+        tokenIn.mint(attacker, 1000 ether);
+        vm.prank(attacker);
+        tokenIn.approve(address(router), type(uint256).max);
+
+        vm.prank(attacker);
+        router.addToBalanceOf(PROJECT_ID, address(tokenIn), 1000 ether, false, "", _metadata(tokenOut));
+
+        assertEq(destTerminal.lastAmount(), 100 ether, "destination only receives filled output");
+        assertEq(
+            tokenIn.balanceOf(attacker), 450 ether, "attacker captures both leftover and preexisting router balance"
+        );
+        assertEq(tokenIn.balanceOf(address(router)), 0, "router balance is fully drained by the refund");
+    }
+
+    function _deployPool(
+        AuditLeftoverMockERC20 tokenIn,
+        AuditLeftoverMockERC20 tokenOut,
+        uint256 amountInUsed,
+        uint256 amountOutGiven
+    )
+        internal
+        returns (AuditLeftoverPartialFillPool pool)
+    {
+        (address token0, address token1) = address(tokenIn) < address(tokenOut)
+            ? (address(tokenIn), address(tokenOut))
+            : (address(tokenOut), address(tokenIn));
+        pool = new AuditLeftoverPartialFillPool(token0, token1, tokenOut, amountInUsed, amountOutGiven);
+    }
+
+    function _metadata(AuditLeftoverMockERC20 tokenOut) internal view returns (bytes memory metadata) {
+        metadata = JBMetadataResolver.addToMetadata(
+            "", JBMetadataResolver.getId("routeTokenOut", address(router)), abi.encode(address(tokenOut))
+        );
+        metadata = JBMetadataResolver.addToMetadata(
+            metadata, JBMetadataResolver.getId("quoteForSwap", address(router)), abi.encode(100 ether)
+        );
+    }
+
+    function _mockSimpleSwapRoute(
+        AuditLeftoverMockERC20 tokenIn,
+        AuditLeftoverMockERC20 tokenOut,
+        AuditLeftoverDestTerminal destTerminal,
+        AuditLeftoverPartialFillPool pool
+    )
+        internal
+    {
+        vm.mockCall(address(tokens), abi.encodeWithSelector(IJBTokens.projectIdOf.selector), abi.encode(uint256(0)));
+        vm.mockCall(
+            address(directory),
+            abi.encodeCall(IJBDirectory.primaryTerminalOf, (PROJECT_ID, address(tokenIn))),
+            abi.encode(address(0))
+        );
+        vm.mockCall(
+            address(directory),
+            abi.encodeCall(IJBDirectory.primaryTerminalOf, (PROJECT_ID, address(tokenOut))),
+            abi.encode(address(destTerminal))
+        );
+        vm.mockCall(
+            address(factory),
+            abi.encodeCall(IUniswapV3Factory.getPool, (address(tokenIn), address(tokenOut), uint24(3000))),
+            abi.encode(address(pool))
+        );
+        vm.mockCall(
+            address(factory),
+            abi.encodeCall(IUniswapV3Factory.getPool, (address(tokenIn), address(tokenOut), uint24(500))),
+            abi.encode(address(0))
+        );
+        vm.mockCall(
+            address(factory),
+            abi.encodeCall(IUniswapV3Factory.getPool, (address(tokenIn), address(tokenOut), uint24(10_000))),
+            abi.encode(address(0))
+        );
+        vm.mockCall(
+            address(factory),
+            abi.encodeCall(IUniswapV3Factory.getPool, (address(tokenIn), address(tokenOut), uint24(100))),
+            abi.encode(address(0))
+        );
+    }
+}

package/test/audit/PayerTrackerRefund.t.sol

@@ -28,9 +28,9 @@ contract PayerTrackerRefundHarness is JBRouterTerminal {
         )
     {}
 
-    /// @notice Public wrapper so tests can call `_resolveRefundTo` directly.
+    /// @notice Public wrapper so tests can call `_resolveRefundWithBackupRecipient` directly.
     function resolveRefundTo(address payable fallback_) external view returns (address payable) {
-        return _resolveRefundTo(fallback_);
+        return _resolveRefundWithBackupRecipient(fallback_);
     }
 }
 

package/test/audit/RefundToBeneficiary.t.sol

@@ -0,0 +1,104 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.28;
+
+import {Test} from "forge-std/Test.sol";
+
+import {JBRouterTerminal} from "../../src/JBRouterTerminal.sol";
+import {IWETH9} from "../../src/interfaces/IWETH9.sol";
+import {IJBPayerTracker} from "../../src/interfaces/IJBPayerTracker.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 {IJBTokens} from "@bananapus/core-v6/src/interfaces/IJBTokens.sol";
+
+import {ERC20} from "@openzeppelin/contracts/token/ERC20/ERC20.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";
+
+contract RefundToBeneficiaryTest is Test {
+    uint256 internal constant LEFTOVER = 40 ether;
+
+    HarnessRouterTerminal internal router;
+    MockERC20 internal token;
+
+    address internal payer = makeAddr("payer");
+    address internal beneficiary = makeAddr("beneficiary");
+
+    function setUp() public {
+        token = new MockERC20("Input", "IN");
+        router = new HarnessRouterTerminal();
+
+        token.mint(address(router), LEFTOVER);
+    }
+
+    function test_directCallerRefundsToBeneficiary() public {
+        vm.prank(payer);
+        router.simulatePayLeftoverRefund(address(token), beneficiary, LEFTOVER);
+
+        assertEq(token.balanceOf(beneficiary), LEFTOVER, "beneficiary receives leftover");
+        assertEq(token.balanceOf(payer), 0, "payer receives nothing");
+    }
+
+    function test_registryStyleCallerRefundsToOriginalPayer() public {
+        MockPayerTracker intermediary = new MockPayerTracker(payer);
+
+        vm.prank(address(intermediary));
+        router.simulatePayLeftoverRefund(address(token), beneficiary, LEFTOVER);
+
+        assertEq(token.balanceOf(payer), LEFTOVER, "intermediary path refunds payer");
+        assertEq(token.balanceOf(beneficiary), 0, "beneficiary receives nothing");
+    }
+}
+
+contract HarnessRouterTerminal is JBRouterTerminal {
+    constructor()
+        JBRouterTerminal(
+            IJBDirectory(address(0)),
+            IJBPermissions(address(0)),
+            IJBProjects(address(0)),
+            IJBTokens(address(0)),
+            IPermit2(address(0)),
+            address(this),
+            IWETH9(address(new MockWETH())),
+            IUniswapV3Factory(address(0)),
+            IPoolManager(address(0)),
+            address(0)
+        )
+    {}
+
+    function simulatePayLeftoverRefund(address token, address beneficiary, uint256 leftover) external {
+        address payable refundTo = _resolveRefundWithBackupRecipient(payable(beneficiary));
+        _transferFrom({from: address(this), to: refundTo, token: token, amount: leftover});
+    }
+}
+
+contract MockPayerTracker is IJBPayerTracker {
+    address public override originalPayer;
+
+    constructor(address payer) {
+        originalPayer = payer;
+    }
+}
+
+    contract MockERC20 is ERC20 {
+        constructor(string memory name, string memory symbol) ERC20(name, symbol) {}
+
+        function mint(address account, uint256 amount) external {
+            _mint(account, amount);
+        }
+    }
+
+    contract MockWETH is MockERC20, IWETH9 {
+        constructor() MockERC20("Wrapped ETH", "WETH") {}
+
+        function deposit() external payable {
+            _mint(msg.sender, msg.value);
+        }
+
+        function withdraw(uint256 wad) external {
+            _burn(msg.sender, wad);
+            payable(msg.sender).transfer(wad);
+        }
+    }

package/test/audit/{CodexRegistryAddToBalancePartialFill.t.sol → RegistryAddToBalancePartialFill.t.sol}

@@ -285,7 +285,7 @@ contract AuditPartialFillPool is IUniswapV3Pool {
     }
 }
 
-contract CodexRegistryAddToBalancePartialFillTest is Test {
+contract RegistryAddToBalancePartialFillTest is Test {
     IJBDirectory directory;
     IJBPermissions permissions;
     IJBProjects projects;