@bananapus/core-v6 0.0.27 → 0.0.28

package/ADMINISTRATION.md

@@ -123,7 +123,7 @@ Admin privileges and their scope in nana-core-v6.
 |----------|--------------|---------------|-------|-------------|
 | `addAccountingContextsFor` | Project owner, operator, or the project's controller | ADD_ACCOUNTING_CONTEXTS (20) | Per project | Adds tokens that the terminal will accept for a project. Requires the ruleset's `allowAddAccountingContext` flag (if a ruleset exists). |
 | `cashOutTokensOf` | Token holder or operator | CASH_OUT_TOKENS (4) | Per project | Cashes out project tokens for a share of the project's surplus. Fees are charged unless the beneficiary is feeless or the cash out tax rate is zero. |
-| `migrateBalanceOf` | Project owner or operator | MIGRATE_TERMINAL (6) | Per project | Migrates a project's balance from this terminal to another. The destination terminal must accept the same token. The ruleset must have `allowTerminalMigration` enabled (checked in JBTerminalStore). |
+| `migrateBalanceOf` | Project owner or operator | MIGRATE_TERMINAL (6) | Per project | Migrates a project's balance from this terminal to another. The destination terminal must accept the same token. The ruleset must have `allowTerminalMigration` enabled (checked in JBTerminalStore). The standard 2.5% protocol fee is charged when migrating to a non-feeless terminal. |
 | `sendPayoutsOf` | Anyone (unless `ownerMustSendPayouts` is set) | SEND_PAYOUTS (5) if `ownerMustSendPayouts` | Per project | Sends payouts to the project's payout split group up to the payout limit. Anyone can call unless the ruleset has `ownerMustSendPayouts` enabled, which requires the project owner or an operator with SEND_PAYOUTS permission. |
 | `useAllowanceOf` | Project owner or operator | USE_ALLOWANCE (17) | Per project | Withdraws funds from the project's surplus up to the surplus allowance. Fees are charged unless the owner or beneficiary is feeless. |
 | `pay` | Anyone | N/A | N/A | Pays a project with tokens. No permission required. |

package/AUDIT_INSTRUCTIONS.md

@@ -88,7 +88,7 @@ Holder -> JBMultiTerminal.cashOutTokensOf()
      -> Fee skipped if beneficiary is feeless
 ```
 
-**Critical note**: The beneficiary receives the reclaim amount BEFORE cash out hooks execute. Fees are taken AFTER hooks. `_feeFreeSurplusOf[projectId][token]` accumulates the value of fee-free intra-terminal payouts. After any outflow (payouts, `useAllowanceOf`, non-zero-tax or feeless cashouts), the counter is capped at the remaining balance — non-fee-free funds leave first. During zero-tax cashout, the 2.5% fee applies only up to this surplus amount (then depletes it), preventing a round-trip fee bypass. Cleared on terminal migration.
+**Critical note**: The beneficiary receives the reclaim amount BEFORE cash out hooks execute. Fees are taken AFTER hooks. `_feeFreeSurplusOf[projectId][token]` accumulates the value of fee-free intra-terminal payouts. After any outflow (payouts, `useAllowanceOf`, non-zero-tax or feeless cashouts), the counter is capped at the remaining balance -- non-fee-free funds leave first. During zero-tax cashout, the 2.5% fee applies only up to this surplus amount (then depletes it), preventing a round-trip fee bypass. Cleared on terminal migration (the migration fee settles this liability).
 
 ### Payout Flow (`sendPayoutsOf`)
 

package/CHANGE_LOG.md

@@ -48,6 +48,14 @@ Also in this release:
 - **`via_ir = true`**: Added to `foundry.toml` to enable the Solidity IR optimizer pipeline, reducing deployed bytecode size (EIP-170 compliance).
 - Internal helpers extracted: `_accountingContextOf` and `_tokenAmountOf` on `JBMultiTerminal`, `_splitTokenCount` on `JBController`.
 
+### 0.6 JBMultiTerminal -- Migration Fee
+
+`migrateBalanceOf` now charges the standard 2.5% protocol fee when migrating to a non-feeless terminal, consistent with all other fund egress. This also settles any `_feeFreeSurplusOf` liability that would otherwise be lost on the new terminal. The fee is deducted from the migrated balance before transfer. Feeless terminals are exempt.
+
+### 0.7 JBMultiTerminal -- Self-Pay Revert
+
+`_pay` now reverts with `JBMultiTerminal_MintNotAllowed()` when `payer == address(this)`. This prevents same-project intra-terminal payout splits (where `preferAddToBalance == false`) from minting tokens against existing balance without new funds entering the system. The try-catch in `JBPayoutSplitGroupLib` catches this revert and restores the balance via `recordAddedBalanceFor`. Projects that want to mint should do so explicitly via the controller.
+
 ---
 
 ## 1. Breaking Changes
@@ -182,6 +190,13 @@ Parameters changed from `memory` to `calldata` for gas efficiency.
 
 ## 3. Event Changes
 
+### 3.0 Indexer Notes
+
+For subgraph migrations, this repo is the protocol-level anchor:
+- when an event signature gains parameters, prefer widening the existing entity schema instead of treating it as an unrelated event stream;
+- preview/noop behavior in core-v6 means some routing diagnostics now come from returned hook specs rather than only from emitted callback events;
+- if your v5 graph correlated protocol actions to hook callbacks only, re-check those assumptions against v6 preview/noop patterns.
+
 ### 3.1 New Events
 
 See section 2.2 above.

package/RISKS.md

@@ -52,13 +52,13 @@ No `ReentrancyGuard` is used. The system relies on state ordering and the `Inade
 | `processHeldFeesOf` | `delete _heldFeesOf[...][currentIndex]`, `_nextHeldFeeIndexOf` incremented | `_processFee` -> `this.executeProcessFee` -> `terminal.pay` | LOW -- index advanced before external call; re-reads from storage each iteration |
 | `_sendReservedTokensToSplitsOf` | `pendingReservedTokenBalanceOf` zeroed, tokens minted to controller | Split hooks, terminal payments | LOW -- pending balance cleared before minting prevents double-distribution |
 | `_useAllowanceOf` | `STORE.recordUsedAllowanceOf` (allowance consumed, balance decremented) | `_takeFeeFrom` (fee payment/holding), `_transferFrom` (beneficiary) | LOW -- allowance consumed before calls |
-| `migrateBalanceOf` | `STORE.recordTerminalMigration` (balance zeroed) | `to.addToBalanceOf` | LOW -- balance zeroed before transfer |
+| `migrateBalanceOf` | `STORE.recordTerminalMigration` (balance zeroed), `_takeFeeFrom` (if non-feeless destination) | `to.addToBalanceOf` | LOW -- balance zeroed before transfer, fee deducted before transfer |
 
 ### Cross-Function Reentrancy to Explore
 
 - **Pay hook -> `cashOutTokensOf`**: After `_pay` mints tokens, a pay hook could call `cashOutTokensOf`. The cash out sees post-payment balance and post-mint supply. Not profitable after fees in tested scenarios, but verify with data hooks that modify weights.
 - **Cash out hook -> `pay`**: During `_cashOutTokensOf`, after tokens are burned and beneficiary is paid, a cash out hook could call `pay()` adding to the balance. Fees haven't been taken yet at this point. Verify the fee calculation on `amountEligibleForFees` isn't affected.
-- **Split hook -> `pay` on same project**: During `sendPayoutsOf`, a split hook receives funds and calls `pay()` on the same project. Payout limit is consumed, but the payment increases balance and mints tokens. The funds came from the project's own balance, so no value creation -- but verify the accounting.
+- **Split hook -> `pay` on same project**: During `sendPayoutsOf`, a split hook receives funds and calls `pay()` on the same project. Payout limit is consumed, but the payment increases balance and mints tokens. The funds came from the project's own balance, so no value creation -- but verify the accounting. Note: `_pay` now reverts with `MintNotAllowed` when `payer == address(this)` to prevent same-project intra-terminal payout splits from minting tokens against existing balance. The try-catch in the split group lib catches this and restores the balance.
 - **Fee processing -> any re-entry**: `_processFee` uses `this.executeProcessFee` (external call via try-catch). Inside, it calls `terminal.pay()` on project #1. If project #1 has a pay hook that calls back, the fee amount is already deducted.
 
 ### Key Backstop
@@ -77,7 +77,7 @@ No `ReentrancyGuard` is used. The system relies on state ordering and the `Inade
 ### Migration
 
 - **Controller migration** requires `allowSetController` in the current ruleset. During migration, `JBController.migrate()` reverts if there are pending reserved tokens. An attacker cannot front-run migration to inflate pending reserves (they'd need mint permission), but a project with organic pending reserves must distribute them first.
-- **Terminal migration** requires `allowTerminalMigration` in the current ruleset. Held fees are intentionally NOT migrated -- they belong to project #1. Verify that a project owner cannot use migration to escape held fee obligations.
+- **Terminal migration** requires `allowTerminalMigration` in the current ruleset. Held fees are intentionally NOT migrated -- they belong to project #1. Migration to a non-feeless terminal charges the standard 2.5% protocol fee on the full balance, settling any `_feeFreeSurplusOf` liability.
 - **Directory updates** (`setTerminalsOf`, `setControllerOf`) are gated by `IJBDirectoryAccessControl` checks that read from the current ruleset's metadata flags. If the current ruleset allows these changes, anyone with the appropriate permission can redirect all of a project's fund flows.
 
 ### Ruleset Queuing

package/USER_JOURNEYS.md

@@ -300,15 +300,18 @@ All user paths through the Juicebox V6 core protocol. For each journey: entry po
 - `to` -- Destination terminal
 
 **State changes**:
-1. `JBTerminalStore.balanceOf[oldTerminal][projectId][token]` set to 0
-2. Funds transferred to destination terminal via `to.addToBalanceOf()`
-3. Destination terminal records the added balance
+1. `_feeFreeSurplusOf[projectId][token]` cleared
+2. `JBTerminalStore.balanceOf[oldTerminal][projectId][token]` set to 0
+3. If destination is non-feeless: 2.5% protocol fee deducted from balance via `_takeFeeFrom`
+4. Remaining funds transferred to destination terminal via `to.addToBalanceOf()`
+5. Destination terminal records the added balance
 
 **Events**: `MigrateTerminal(projectId, token, to, amount, caller)`
 
 **Edge cases**:
 - Requires `allowTerminalMigration` in current ruleset
 - Destination terminal must have accounting context for the token (validated via `accountingContextForTokenOf`)
+- **Standard 2.5% protocol fee** is charged when migrating to a non-feeless terminal, consistent with all other fund egress. This also settles any `_feeFreeSurplusOf` liability.
 - **Held fees are NOT transferred** -- they remain in the old terminal. Held fees belong to the fee beneficiary (project #1), not the migrating project.
 - If balance is 0, no transfer occurs
 - This only migrates one token's balance. Must be called once per token.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/core-v6",
-  "version": "0.0.27",
+  "version": "0.0.28",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -26,14 +26,14 @@
     "artifacts": "source ./.env && npx sphinx artifacts --org-id 'ea165b21-7cdc-4d7b-be59-ecdd4c26bee4' --project-name 'nana-core-v6'"
   },
   "dependencies": {
-    "@bananapus/address-registry-v6": "^0.0.15",
+    "@bananapus/address-registry-v6": "^0.0.16",
     "@bananapus/permission-ids-v6": "^0.0.14",
-    "@chainlink/contracts": "^1.3.0",
+    "@chainlink/contracts": "^1.5.0",
     "@openzeppelin/contracts": "^5.6.1",
     "@prb/math": "^4.1.1",
     "@uniswap/permit2": "github:Uniswap/permit2"
   },
   "devDependencies": {
-    "@sphinx-labs/plugins": "^0.33.2"
+    "@sphinx-labs/plugins": "^0.33.3"
   }
 }

package/src/JBMultiTerminal.sol

@@ -59,6 +59,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     //*********************************************************************//
 
     error JBMultiTerminal_FeeTerminalNotFound(address token);
+    error JBMultiTerminal_MintNotAllowed();
     error JBMultiTerminal_NoMsgValueAllowed(uint256 value);
     error JBMultiTerminal_OverflowAlert(uint256 value, uint256 limit);
     error JBMultiTerminal_PermitAllowanceNotEnough(uint256 amount, uint256 allowance);
@@ -386,6 +387,15 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
                     metadata: metadata
                 });
             } else {
+                // Revert if this is a self-referencing payout (project paying itself via a split).
+                // Same-project pay splits would mint tokens against existing balance without new funds entering.
+                // Projects that want to mint should do so explicitly via the controller.
+                // Cross-project pay splits on the same terminal are allowed (different project receives the funds).
+                // The try-catch in the split group lib catches this revert and restores the balance.
+                if (terminal == this && split.projectId == projectId) {
+                    revert JBMultiTerminal_MintNotAllowed();
+                }
+
                 // Keep a reference to the beneficiary of the payment.
                 address beneficiary = split.beneficiary != address(0) ? split.beneficiary : originalMessageSender;
 
@@ -492,12 +502,14 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             revert JBMultiTerminal_TerminalTokensIncompatible({projectId: projectId, token: token, terminal: to});
         }
 
-        // Clear fee-free surplus tracking before migration. The new terminal has no fee-free history.
-        // This prevents stale fee-free surplus from persisting if the project later migrates back.
+        // Clear fee-free surplus tracking — the fee-free liability is settled by the migration fee below.
         delete _feeFreeSurplusOf[projectId][token];
 
         // Terminal migration intentionally does not transfer held fees. Held fees belong to the
         // fee beneficiary (project #1), not the migrating project. They unlock after 28 days regardless of terminal.
+        // After migration, `processHeldFeesOf()` on this terminal still works — it reads from `_heldFeesOf` and
+        // sends fees to the fee project terminal. The migrated project's balance on this terminal is zero, but held
+        // fees are backed by the terminal's own token balance (not the project's recorded balance).
         // Record the migration in the store.
         // slither-disable-next-line reentrancy-events
         balance = STORE.recordTerminalMigration({projectId: projectId, token: token});
@@ -506,17 +518,33 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
 
         // Transfer the balance if needed.
         if (balance != 0) {
+            // Migration to a non-feeless terminal incurs the standard 2.5% fee, same as any other fund egress.
+            // This also settles any fee-free surplus liability that would otherwise be lost on the new terminal.
+            uint256 feeAmount;
+            if (!_isFeeless(address(to)) && projectId != _FEE_BENEFICIARY_PROJECT_ID) {
+                feeAmount = _takeFeeFrom({
+                    projectId: projectId,
+                    token: token,
+                    amount: balance,
+                    beneficiary: payable(_ownerOf(projectId)),
+                    shouldHoldFees: false
+                });
+            }
+
+            // Transfer the balance minus the fee to the new terminal.
+            uint256 migrationAmount = balance - feeAmount;
+
             // Trigger any inherited pre-transfer logic.
             // If this terminal's token is the native token, send it in `msg.value`.
             // slither-disable-next-line reentrancy-events
-            uint256 payValue = _beforeTransferTo({to: address(to), token: token, amount: balance});
+            uint256 payValue = _beforeTransferTo({to: address(to), token: token, amount: migrationAmount});
 
-            // Withdraw the balance to transfer to the new terminal;
+            // Withdraw the balance to transfer to the new terminal.
             // slither-disable-next-line reentrancy-events
             to.addToBalanceOf{value: payValue}({
                 projectId: projectId,
                 token: token,
-                amount: balance,
+                amount: migrationAmount,
                 shouldReturnHeldFees: false,
                 memo: "",
                 metadata: bytes("")
@@ -584,13 +612,13 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     /// @notice Process any fees that are being held for the project.
     /// @dev Reentrancy safety: the loop re-reads `_nextHeldFeeIndexOf` from storage each iteration and advances the
     /// index before the external `_processFee` call, so a reentrant call cannot double-process the same fee entry.
-    /// @dev Phantom balance risk: after a terminal migration, held fees remain in this terminal but the backing tokens
-    /// have been transferred to the new terminal via `migrateBalanceOf`. If `_processFee` reverts (e.g. the fee
-    /// terminal rejects the payment), the catch block calls `_recordAddedBalanceFor`, which credits the project's
-    /// recorded balance without any actual tokens arriving — creating a phantom balance. This is an accepted
-    /// trade-off:
-    /// the alternative (losing the fee amount entirely on revert) is worse. Callers should be aware that processing
-    /// held fees post-migration may inflate the project's recorded balance if any fee payments revert.
+    /// @dev Held fees after migration: held fees remain in this terminal after `migrateBalanceOf` because their backing
+    /// tokens are not part of `balanceOf` — they were already deducted from the recorded balance during the payout
+    /// that
+    /// created them. The actual fee-backing tokens remain in this terminal's token holdings. If `_processFee` reverts
+    /// (e.g. the fee terminal rejects the payment), the catch block calls `_recordAddedBalanceFor` to credit the fee
+    /// amount back to the project. This credit is backed by the tokens that failed to transfer out. No phantom balance
+    /// is created because the tokens never left.
     /// @dev The index-increment-before-`_processFee` pattern is intentional: locked (not-yet-unlocked) fees are skipped
     /// via the `unlockTimestamp` check, and advancing the index before the external call prevents reentrancy from
     /// reprocessing the same fee entry.

package/test/TestFees.sol

@@ -216,8 +216,9 @@ contract TestFees_Local is TestBaseWorkflow {
         // Send: Migration to terminal2
         _terminal.migrateBalanceOf(_projectId, JBConstants.NATIVE_TOKEN, _terminal2);
 
-        // Check: Held Fee is processed and feeAmount remains in terminal
-        assertEq(address(_terminal).balance, _feeAmount);
+        // Check: Held fee remains in terminal, plus migration fee paid to fee project (on same terminal)
+        uint256 _migrationFee = _nativeDistLimit * _terminal.FEE() / JBConstants.MAX_FEE;
+        assertEq(address(_terminal).balance, _feeAmount + _migrationFee);
 
         vm.stopPrank();
     }
@@ -265,8 +266,9 @@ contract TestFees_Local is TestBaseWorkflow {
         // Send: Migration to terminal2
         _terminal.migrateBalanceOf(_projectId, JBConstants.NATIVE_TOKEN, _terminal2);
 
-        // Check: Held fee has been repaid, no balance remains.
-        assertEq(address(_terminal).balance, 0);
+        // Check: Held fee has been repaid. Migration fee paid to fee project remains on this terminal.
+        uint256 _migrationFee = _nativePayAmount * _terminal.FEE() / JBConstants.MAX_FEE;
+        assertEq(address(_terminal).balance, _migrationFee);
 
         vm.stopPrank();
     }

package/test/TestTerminalMigration.sol

@@ -6,6 +6,7 @@ import {JBMultiTerminal} from "../src/JBMultiTerminal.sol";
 import {IJBController} from "../src/interfaces/IJBController.sol";
 import {IJBRulesetApprovalHook} from "../src/interfaces/IJBRulesetApprovalHook.sol";
 import {JBConstants} from "../src/libraries/JBConstants.sol";
+import {JBFees} from "../src/libraries/JBFees.sol";
 import {JBAccountingContext} from "../src/structs/JBAccountingContext.sol";
 import {JBFundAccessLimitGroup} from "../src/structs/JBFundAccessLimitGroup.sol";
 import {JBRulesetConfig} from "../src/structs/JBRulesetConfig.sol";
@@ -105,7 +106,7 @@ contract TestTerminalMigration_Local is TestBaseWorkflow {
         uint256 migratedBalance = _terminalA.migrateBalanceOf(_projectId, JBConstants.NATIVE_TOKEN, _terminalB);
         assertEq(migratedBalance, payAmount, "full balance should be migrated");
 
-        // Step 4: Verify balances after migration
+        // Step 4: Verify balances after migration (fee project is exempt from migration fee)
         uint256 balanceAAfter = jbTerminalStore().balanceOf(address(_terminalA), _projectId, JBConstants.NATIVE_TOKEN);
         assertEq(balanceAAfter, 0, "terminal A should have zero after migration");
 
@@ -152,7 +153,7 @@ contract TestTerminalMigration_Local is TestBaseWorkflow {
         vm.prank(_projectOwner);
         _terminalA.migrateBalanceOf(_projectId, JBConstants.NATIVE_TOKEN, _terminalB);
 
-        // Check surplus from terminal B
+        // Check surplus from terminal B (fee project exempt from migration fee)
         uint256 surplusAfter =
             _terminalB.currentSurplusOf(_projectId, new address[](0), 18, uint32(uint160(JBConstants.NATIVE_TOKEN)));
         assertEq(surplusAfter, surplusBefore, "surplus should be preserved after migration");
@@ -169,4 +170,105 @@ contract TestTerminalMigration_Local is TestBaseWorkflow {
         vm.expectRevert();
         _terminalA.migrateBalanceOf(_projectId, JBConstants.NATIVE_TOKEN, _terminalB);
     }
+
+    /// @notice Non-fee project migration charges the 2.5% fee; fee project balance increases.
+    function test_migration_nonFeeProject_chargesFee() public {
+        // Launch a second project (project 2) — this is NOT the fee project.
+        JBRulesetMetadata memory _metadata2 = JBRulesetMetadata({
+            reservedPercent: 0,
+            cashOutTaxRate: 0,
+            baseCurrency: uint32(uint160(JBConstants.NATIVE_TOKEN)),
+            pausePay: false,
+            pauseCreditTransfers: false,
+            allowOwnerMinting: false,
+            allowSetCustomToken: false,
+            allowTerminalMigration: true,
+            allowSetTerminals: true,
+            allowSetController: false,
+            allowAddAccountingContext: false,
+            allowAddPriceFeed: false,
+            ownerMustSendPayouts: false,
+            holdFees: false,
+            useTotalSurplusForCashOuts: false,
+            useDataHookForPay: false,
+            useDataHookForCashOut: false,
+            dataHook: address(0),
+            metadata: 0
+        });
+
+        JBRulesetConfig[] memory _rulesetConfig2 = new JBRulesetConfig[](1);
+        _rulesetConfig2[0].mustStartAtOrAfter = 0;
+        _rulesetConfig2[0].duration = 0;
+        _rulesetConfig2[0].weight = 1000 * 10 ** 18;
+        _rulesetConfig2[0].weightCutPercent = 0;
+        _rulesetConfig2[0].approvalHook = IJBRulesetApprovalHook(address(0));
+        _rulesetConfig2[0].metadata = _metadata2;
+        _rulesetConfig2[0].splitGroups = new JBSplitGroup[](0);
+        _rulesetConfig2[0].fundAccessLimitGroups = new JBFundAccessLimitGroup[](0);
+
+        JBAccountingContext[] memory _tokensToAccept = new JBAccountingContext[](1);
+        _tokensToAccept[0] = JBAccountingContext({
+            token: JBConstants.NATIVE_TOKEN, decimals: 18, currency: uint32(uint160(JBConstants.NATIVE_TOKEN))
+        });
+
+        JBTerminalConfig[] memory _terminalConfigs2 = new JBTerminalConfig[](2);
+        _terminalConfigs2[0] = JBTerminalConfig({terminal: _terminalA, accountingContextsToAccept: _tokensToAccept});
+        _terminalConfigs2[1] = JBTerminalConfig({terminal: _terminalB, accountingContextsToAccept: _tokensToAccept});
+
+        uint256 project2 = _controller.launchProjectFor({
+            owner: _projectOwner,
+            projectUri: "non-fee-project",
+            rulesetConfigurations: _rulesetConfig2,
+            terminalConfigurations: _terminalConfigs2,
+            memo: ""
+        });
+
+        // Confirm project 2 is NOT the fee project.
+        assertGt(project2, 1, "project2 should not be the fee project");
+
+        uint256 payAmount = 10 ether;
+
+        // Pay into terminal A for project 2.
+        vm.deal(_beneficiary, payAmount);
+        vm.prank(_beneficiary);
+        _terminalA.pay{value: payAmount}(project2, JBConstants.NATIVE_TOKEN, payAmount, _beneficiary, 0, "", "");
+
+        // Snapshot fee project balance before migration.
+        uint256 feeBalanceBefore = jbTerminalStore().balanceOf(address(_terminalA), 1, JBConstants.NATIVE_TOKEN);
+
+        // Migrate project 2 from terminal A to terminal B.
+        vm.prank(_projectOwner);
+        _terminalA.migrateBalanceOf(project2, JBConstants.NATIVE_TOKEN, _terminalB);
+
+        // Fee project balance should have increased (fee was charged).
+        uint256 feeBalanceAfter = jbTerminalStore().balanceOf(address(_terminalA), 1, JBConstants.NATIVE_TOKEN);
+        assertGt(feeBalanceAfter, feeBalanceBefore, "fee project should receive migration fee");
+
+        // Terminal B should have received payAmount minus the 2.5% fee.
+        uint256 expectedFee = JBFees.feeAmountFrom({amountBeforeFee: payAmount, feePercent: 25});
+        uint256 balanceBAfter = jbTerminalStore().balanceOf(address(_terminalB), project2, JBConstants.NATIVE_TOKEN);
+        assertEq(balanceBAfter, payAmount - expectedFee, "terminal B balance should reflect fee deduction");
+    }
+
+    /// @notice Fee project (project 1) migration is exempt from fees.
+    function test_migration_feeProject_noFeeCharged() public {
+        // _projectId is project 1, which IS the fee project.
+        assertEq(_projectId, 1, "project under test should be the fee project");
+
+        uint256 payAmount = 10 ether;
+
+        // Pay into terminal A for the fee project.
+        vm.deal(_beneficiary, payAmount);
+        vm.prank(_beneficiary);
+        _terminalA.pay{value: payAmount}(_projectId, JBConstants.NATIVE_TOKEN, payAmount, _beneficiary, 0, "", "");
+
+        // Migrate fee project from terminal A to terminal B.
+        vm.prank(_projectOwner);
+        uint256 migratedBalance = _terminalA.migrateBalanceOf(_projectId, JBConstants.NATIVE_TOKEN, _terminalB);
+        assertEq(migratedBalance, payAmount, "full balance should be migrated without fee");
+
+        // Terminal B should have the full amount (no fee deducted).
+        uint256 balanceBAfter = jbTerminalStore().balanceOf(address(_terminalB), _projectId, JBConstants.NATIVE_TOKEN);
+        assertEq(balanceBAfter, payAmount, "fee project should not be charged migration fee");
+    }
 }

package/test/audit/FeeFreeSurplusLifecycle.t.sol

@@ -318,10 +318,13 @@ contract FeeFreeSurplusLifecycleTest is TestBaseWorkflow {
             jbTerminalStore().balanceOf(address(_terminal), _recipientProjectId, JBConstants.NATIVE_TOKEN);
         assertEq(balanceAfterOnOldTerminal, 0, "Old terminal balance should be zero after migration");
 
-        // Verify the new terminal received the balance.
+        // Verify the new terminal received the balance minus the 2.5% migration fee.
         uint256 balanceOnNewTerminal =
             jbTerminalStore().balanceOf(address(_terminal2), _recipientProjectId, JBConstants.NATIVE_TOKEN);
-        assertEq(balanceOnNewTerminal, balanceBefore, "New terminal should have the migrated balance");
+        uint256 migrationFee = balanceBefore * 25 / 1000;
+        assertEq(
+            balanceOnNewTerminal, balanceBefore - migrationFee, "New terminal should have balance minus migration fee"
+        );
     }
 
     // --- Helpers ---

package/test/units/static/JBMultiTerminal/TestExecutePayout.sol

@@ -4,18 +4,14 @@ pragma solidity 0.8.28;
 import {JBMultiTerminal} from "../../../../src/JBMultiTerminal.sol";
 import {IJBDirectory} from "../../../../src/interfaces/IJBDirectory.sol";
 import {IJBFeelessAddresses} from "../../../../src/interfaces/IJBFeelessAddresses.sol";
-import {IJBRulesetApprovalHook} from "../../../../src/interfaces/IJBRulesetApprovalHook.sol";
 import {IJBSplitHook} from "../../../../src/interfaces/IJBSplitHook.sol";
 import {IJBTerminal} from "../../../../src/interfaces/IJBTerminal.sol";
 import {IJBTerminalStore} from "../../../../src/interfaces/IJBTerminalStore.sol";
 import {JBConstants} from "../../../../src/libraries/JBConstants.sol";
 import {JBFees} from "../../../../src/libraries/JBFees.sol";
 import {JBAccountingContext} from "../../../../src/structs/JBAccountingContext.sol";
-import {JBPayHookSpecification} from "../../../../src/structs/JBPayHookSpecification.sol";
-import {JBRuleset} from "../../../../src/structs/JBRuleset.sol";
 import {JBSplit} from "../../../../src/structs/JBSplit.sol";
 import {JBSplitHookContext} from "../../../../src/structs/JBSplitHookContext.sol";
-import {JBTokenAmount} from "../../../../src/structs/JBTokenAmount.sol";
 import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
 import {IERC165} from "@openzeppelin/contracts/utils/introspection/ERC165.sol";
 import {JBMultiTerminalSetup} from "./JBMultiTerminalSetup.sol";
@@ -366,9 +362,7 @@ contract TestExecutePayout_Local is JBMultiTerminalSetup {
     }
 
     function test_GivenPreferAddToBalanceDNEQTrueAndTerminalEQThisAddress() external {
-        // it will call internal _pay
-
-        _setAccountingContext(_projectId, _usdc, 0, _usdcCurrency);
+        // it will revert with MintNotAllowed because same-project same-terminal pay splits are blocked
 
         // mock call to directory primaryTerminalOf
         mockExpect(
@@ -386,41 +380,8 @@ contract TestExecutePayout_Local is JBMultiTerminalSetup {
             hook: IJBSplitHook(address(0))
         });
 
-        // needed for next mock call returns
-        JBTokenAmount memory tokenAmount =
-            JBTokenAmount({token: _usdc, decimals: 0, currency: _usdcCurrency, value: _defaultAmount});
-        JBPayHookSpecification[] memory hookSpecifications = new JBPayHookSpecification[](0);
-        JBRuleset memory returnedRuleset = JBRuleset({
-            cycleNumber: 1,
-            id: 1,
-            basedOnId: 0,
-            start: 0,
-            duration: 0,
-            weight: 0,
-            weightCutPercent: 0,
-            approvalHook: IJBRulesetApprovalHook(address(0)),
-            metadata: 0
-        });
-
-        // mock call to JBTerminalStore recordPaymentFrom
-        mockExpect(
-            address(store),
-            abi.encodeCall(
-                IJBTerminalStore.recordPaymentFrom,
-                (
-                    address(_terminal),
-                    tokenAmount,
-                    _projectId,
-                    address(this),
-                    bytes(abi.encodePacked(uint256(_projectId)))
-                )
-            ),
-            abi.encode(returnedRuleset, 0, hookSpecifications)
-        );
-
-        // for safe ERC20 check of code length at token address
         vm.prank(address(_terminal));
-
+        vm.expectRevert(JBMultiTerminal.JBMultiTerminal_MintNotAllowed.selector);
         JBMultiTerminal(address(_terminal))
             .executePayout({
                 split: _splitMemory,

package/test/units/static/JBMultiTerminal/TestMigrateBalanceOf.sol

@@ -11,6 +11,7 @@ import {JBAccountingContext} from "../../../../src/structs/JBAccountingContext.s
 import {JBPermissionIds} from "@bananapus/permission-ids-v6/src/JBPermissionIds.sol";
 import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
 import {IERC721} from "@openzeppelin/contracts/token/ERC721/IERC721.sol";
+import {IJBFeelessAddresses} from "../../../../src/interfaces/IJBFeelessAddresses.sol";
 import {JBMultiTerminalSetup} from "./JBMultiTerminalSetup.sol";
 
 contract TestMigrateBalanceOf_Local is JBMultiTerminalSetup {
@@ -104,6 +105,13 @@ contract TestMigrateBalanceOf_Local is JBMultiTerminalSetup {
     function test_GivenTokenIsERC20() external whenPermissioned {
         // it will safeIncreaseAllowance and addToBalanceOf
 
+        // mock _isFeeless to return true (skip migration fee for this unit test)
+        mockExpect(
+            address(feelessAddresses),
+            abi.encodeCall(IJBFeelessAddresses.isFeeless, (address(_newTerminal))),
+            abi.encode(true)
+        );
+
         // for next mock
         // forge-lint: disable-next-line(unsafe-typecast)
         JBAccountingContext memory _context =
@@ -143,6 +151,13 @@ contract TestMigrateBalanceOf_Local is JBMultiTerminalSetup {
     function test_GivenTokenIsNative() external whenPermissioned {
         // it will addToBalanceOf with value in msgvalue
 
+        // mock _isFeeless to return true (skip migration fee for this unit test)
+        mockExpect(
+            address(feelessAddresses),
+            abi.encodeCall(IJBFeelessAddresses.isFeeless, (address(_newTerminal))),
+            abi.encode(true)
+        );
+
         // for next mock
         // forge-lint: disable-next-line(unsafe-typecast)
         JBAccountingContext memory _context =

package/test/units/static/JBMultiTerminal/TestSelfPayRevert.sol

@@ -0,0 +1,55 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.28;
+
+import {JBMultiTerminal} from "../../../../src/JBMultiTerminal.sol";
+import {IJBDirectory} from "../../../../src/interfaces/IJBDirectory.sol";
+import {JBConstants} from "../../../../src/libraries/JBConstants.sol";
+import {JBSplit} from "../../../../src/structs/JBSplit.sol";
+import {IJBSplitHook} from "../../../../src/interfaces/IJBSplitHook.sol";
+import {JBMultiTerminalSetup} from "./JBMultiTerminalSetup.sol";
+
+/// @notice Tests that a pay-type split back into the same terminal reverts with MintNotAllowed.
+contract TestSelfPayRevert_Local is JBMultiTerminalSetup {
+    uint64 _projectId = 1;
+    uint256 _defaultAmount = 1e18;
+    address _sender = makeAddr("sender");
+    address _native = JBConstants.NATIVE_TOKEN;
+
+    function setUp() public {
+        super.multiTerminalSetup();
+    }
+
+    /// @notice When a split routes a pay back to the same project on the same terminal,
+    /// executePayout should revert with MintNotAllowed.
+    function test_RevertWhen_SplitPaysBackToSameTerminal() external {
+        // Build a split targeting the SAME project with preferAddToBalance = false (pay path).
+        JBSplit memory split = JBSplit({
+            preferAddToBalance: false,
+            percent: 1_000_000_000,
+            projectId: _projectId,
+            beneficiary: payable(_sender),
+            lockedUntil: 0,
+            hook: IJBSplitHook(address(0))
+        });
+
+        // Mock primaryTerminalOf to return this terminal (self-referencing).
+        mockExpect(
+            address(directory),
+            abi.encodeCall(IJBDirectory.primaryTerminalOf, (_projectId, _native)),
+            abi.encode(address(_terminal))
+        );
+
+        // executePayout requires msg.sender == address(this), so we call it via the terminal.
+        // The terminal's try-catch in the split group lib would normally catch this.
+        vm.prank(address(_terminal));
+        vm.expectRevert(JBMultiTerminal.JBMultiTerminal_MintNotAllowed.selector);
+        JBMultiTerminal(payable(address(_terminal)))
+            .executePayout({
+                split: split,
+                projectId: uint256(_projectId),
+                token: _native,
+                amount: _defaultAmount,
+                originalMessageSender: _sender
+            });
+    }
+}