@bananapus/core-v6 0.0.26 → 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

@@ -6,7 +6,7 @@ Read [RISKS.md](./RISKS.md) for known risks, trust model, and reentrancy analysi
 
 ## Architecture Overview
 
-16 contracts, ~8,100 lines in main contracts. All contracts use Solidity ^0.8.26.
+16 contracts, ~8,100 lines in main contracts. All contracts use Solidity 0.8.28.
 
 ```
                               JBProjects (ERC-721)
@@ -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`)
 
@@ -420,7 +420,7 @@ The 185 test files cover most flows, but these areas have limited or no coverage
 
 ## Compiler and Version Info
 
-- **Solidity**: ^0.8.26
+- **Solidity**: 0.8.28
 - **EVM target**: Cancun (uses transient storage opcodes)
 - **Optimizer**: 200 runs (no via-IR)
 - **Dependencies**: OpenZeppelin 5.x, Solady, forge-std

package/CHANGE_LOG.md

@@ -1,6 +1,6 @@
 # nana-core-v6 Changelog (v5 -> v6)
 
-This document describes all changes between `nana-core` (v5, Solidity 0.8.23) and `nana-core-v6` (v6, Solidity ^0.8.26).
+This document describes all changes between `nana-core` (v5, Solidity 0.8.23) and `nana-core-v6` (v6, Solidity 0.8.28).
 
 ## Summary
 
@@ -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.
@@ -375,7 +390,7 @@ No changes.
 
 ### 8.10 Solidity Version
 
-All contracts upgraded from `pragma solidity 0.8.23` to `pragma solidity ^0.8.26`.
+All contracts upgraded from `pragma solidity 0.8.23` to `pragma solidity 0.8.28`.
 
 ### 8.11 Named Arguments
 

package/README.md

@@ -100,7 +100,7 @@ Projects can migrate between controllers using the `IJBMigratable` interface. Th
 
 Juicebox V6 separates concerns across specialized contracts that coordinate through a central directory. Projects are represented as ERC-721 NFTs. Each project configures rulesets that dictate how payments, payouts, cash outs, and token minting behave over time.
 
-All contracts use Solidity `^0.8.26`.
+All contracts use Solidity `0.8.28`.
 
 ```mermaid
 graph TD;

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/SKILLS.md

@@ -417,7 +417,7 @@ Returns whether `addr` is allowed to mint tokens for the project. Called by `JBC
 
 ```solidity
 // SPDX-License-Identifier: MIT
-pragma solidity ^0.8.26;
+pragma solidity 0.8.28;
 
 import {IJBController} from "@bananapus/core-v6/src/interfaces/IJBController.sol";
 import {IJBDirectory} from "@bananapus/core-v6/src/interfaces/IJBDirectory.sol";

package/STYLE_GUIDE.md

@@ -21,7 +21,7 @@ One contract/interface/struct/enum per file. Name the file after the type it con
 
 ```solidity
 // Contracts — pin to exact version
-pragma solidity ^0.8.26;
+pragma solidity 0.8.28;
 
 // Interfaces, structs, enums — caret for forward compatibility
 pragma solidity ^0.8.0;
@@ -331,7 +331,7 @@ Standard config across all repos:
 
 ```toml
 [profile.default]
-solc = '0.8.26'
+solc = '0.8.28'
 evm_version = 'cancun'
 optimizer_runs = 200
 libs = ["node_modules", "lib"]

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/foundry.toml

@@ -1,5 +1,5 @@
 [profile.default]
-solc = '0.8.26'
+solc = '0.8.28'
 evm_version = 'cancun'
 optimizer_runs = 200
 libs = ["node_modules", "lib"]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/core-v6",
-  "version": "0.0.26",
+  "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.14",
-    "@bananapus/permission-ids-v6": "^0.0.12",
-    "@chainlink/contracts": "^1.3.0",
+    "@bananapus/address-registry-v6": "^0.0.16",
+    "@bananapus/permission-ids-v6": "^0.0.14",
+    "@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/script/Deploy.s.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity ^0.8.26;
+pragma solidity 0.8.28;
 
 import {Sphinx} from "@sphinx-labs/contracts/contracts/foundry/SphinxPlugin.sol";
 import {Script} from "forge-std/Script.sol";

package/script/DeployPeriphery.s.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity ^0.8.26;
+pragma solidity 0.8.28;
 
 import {Sphinx} from "@sphinx-labs/contracts/contracts/foundry/SphinxPlugin.sol";
 import {Script} from "forge-std/Script.sol";

package/script/helpers/CoreDeploymentLib.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity ^0.8.26;
+pragma solidity 0.8.28;
 
 import {stdJson} from "forge-std/Script.sol";
 import {Vm} from "forge-std/Vm.sol";

package/src/JBChainlinkV3PriceFeed.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity ^0.8.26;
+pragma solidity 0.8.28;
 
 import {AggregatorV3Interface} from "@chainlink/contracts/src/v0.8/shared/interfaces/AggregatorV3Interface.sol";
 

package/src/JBChainlinkV3SequencerPriceFeed.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity ^0.8.26;
+pragma solidity 0.8.28;
 
 import {AggregatorV2V3Interface} from "@chainlink/contracts/src/v0.8/shared/interfaces/AggregatorV2V3Interface.sol";
 import {AggregatorV3Interface} from "@chainlink/contracts/src/v0.8/shared/interfaces/AggregatorV3Interface.sol";

package/src/JBController.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity ^0.8.26;
+pragma solidity 0.8.28;
 
 import {JBPermissionIds} from "@bananapus/permission-ids-v6/src/JBPermissionIds.sol";
 import {ERC2771Context} from "@openzeppelin/contracts/metatx/ERC2771Context.sol";

package/src/JBDeadline.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity ^0.8.26;
+pragma solidity 0.8.28;
 
 import {IERC165} from "@openzeppelin/contracts/utils/introspection/IERC165.sol";
 

package/src/JBDirectory.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity ^0.8.26;
+pragma solidity 0.8.28;
 
 import {JBPermissionIds} from "@bananapus/permission-ids-v6/src/JBPermissionIds.sol";
 import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";

package/src/JBERC20.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity ^0.8.26;
+pragma solidity 0.8.28;
 
 import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";
 import {ERC20} from "@openzeppelin/contracts/token/ERC20/ERC20.sol";

package/src/JBFeelessAddresses.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity ^0.8.26;
+pragma solidity 0.8.28;
 
 import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";
 import {IERC165} from "@openzeppelin/contracts/utils/introspection/IERC165.sol";

package/src/JBFundAccessLimits.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity ^0.8.26;
+pragma solidity 0.8.28;
 
 import {JBControlled} from "./abstract/JBControlled.sol";
 import {IJBDirectory} from "./interfaces/IJBDirectory.sol";

package/src/JBMultiTerminal.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity ^0.8.26;
+pragma solidity 0.8.28;
 
 import {JBPermissionIds} from "@bananapus/permission-ids-v6/src/JBPermissionIds.sol";
 import {ERC2771Context} from "@openzeppelin/contracts/metatx/ERC2771Context.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/src/JBPermissions.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity ^0.8.26;
+pragma solidity 0.8.28;
 
 import {JBPermissionIds} from "@bananapus/permission-ids-v6/src/JBPermissionIds.sol";
 import {ERC2771Context} from "@openzeppelin/contracts/metatx/ERC2771Context.sol";

package/src/JBPrices.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity ^0.8.26;
+pragma solidity 0.8.28;
 
 import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";
 import {ERC2771Context, Context} from "@openzeppelin/contracts/metatx/ERC2771Context.sol";

package/src/JBProjects.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity ^0.8.26;
+pragma solidity 0.8.28;
 
 import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";
 import {ERC2771Context} from "@openzeppelin/contracts/metatx/ERC2771Context.sol";

package/src/JBRulesets.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity ^0.8.26;
+pragma solidity 0.8.28;
 
 import {mulDiv} from "@prb/math/src/Common.sol";
 

package/src/JBSplits.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity ^0.8.26;
+pragma solidity 0.8.28;
 
 import {JBControlled} from "./abstract/JBControlled.sol";
 import {IJBDirectory} from "./interfaces/IJBDirectory.sol";

package/src/JBTerminalStore.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity ^0.8.26;
+pragma solidity 0.8.28;
 
 import {mulDiv} from "@prb/math/src/Common.sol";
 import {IERC20Metadata} from "@openzeppelin/contracts/token/ERC20/extensions/IERC20Metadata.sol";

package/src/JBTokens.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity ^0.8.26;
+pragma solidity 0.8.28;
 
 import {Clones} from "@openzeppelin/contracts/proxy/Clones.sol";
 

package/src/libraries/JBPayoutSplitGroupLib.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity ^0.8.26;
+pragma solidity 0.8.28;
 
 import {mulDiv} from "@prb/math/src/Common.sol";
 

package/src/periphery/JBDeadline1Day.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity ^0.8.26;
+pragma solidity 0.8.28;
 
 import {JBDeadline} from "../JBDeadline.sol";
 

package/src/periphery/JBDeadline3Days.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity ^0.8.26;
+pragma solidity 0.8.28;
 
 import {JBDeadline} from "../JBDeadline.sol";
 

package/src/periphery/JBDeadline3Hours.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity ^0.8.26;
+pragma solidity 0.8.28;
 
 import {JBDeadline} from "../JBDeadline.sol";
 

package/src/periphery/JBDeadline7Days.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity ^0.8.26;
+pragma solidity 0.8.28;
 
 import {JBDeadline} from "../JBDeadline.sol";
 

package/src/periphery/JBMatchingPriceFeed.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity ^0.8.26;
+pragma solidity 0.8.28;
 
 import {IJBPriceFeed} from "src/interfaces/IJBPriceFeed.sol";
 

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/TestJBERC20Inheritance.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity ^0.8.26;
+pragma solidity 0.8.28;
 
 import {TestBaseWorkflow} from "./helpers/TestBaseWorkflow.sol";
 import {JBERC20} from "../src/JBERC20.sol";

package/test/TestMetadataOffsetOverflow.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity ^0.8.26;
+pragma solidity 0.8.28;
 
 import {Test} from "forge-std/Test.sol";
 import {MetadataResolverHelper} from "./helpers/MetadataResolverHelper.sol";

package/test/TestMetadataParserLib.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity ^0.8.26;
+pragma solidity 0.8.28;
 
 import {Test} from "forge-std/Test.sol";
 import {MetadataResolverHelper} from "./helpers/MetadataResolverHelper.sol";