@bananapus/core-v6 0.0.27 → 0.0.29

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

@@ -22,8 +22,8 @@ src/
 ├── JBERC20.sol            — Cloneable ERC20Votes+Permit token
 ├── JBFeelessAddresses.sol — Fee-exempt address registry
 ├── JBDeadline.sol         — Approval hook requiring minimum delay
-├── JBChainlinkV3PriceFeed.sol          — Chainlink v3 price feed with staleness check
-├── JBChainlinkV3SequencerPriceFeed.sol — L2 sequencer-aware price feed
+├── JBChainlinkV3PriceFeed.sol          — Chainlink v3 price feed with staleness + answeredInRound check
+├── JBChainlinkV3SequencerPriceFeed.sol — L2 sequencer-aware price feed (answer != 0 = down)
 ├── abstract/
 │   ├── JBPermissioned.sol — Base for permission-checked contracts
 │   └── JBControlled.sol   — Base for controller-gated contracts
@@ -136,7 +136,7 @@ Owner -> JBMultiTerminal.sendPayoutsOf()
 | Data Hook (cashout) | `IJBRulesetDataHook.beforeCashOutRecordedWith` | JBTerminalStore |
 | Pay Hook | `IJBPayHook.afterPayRecordedWith` | JBMultiTerminal |
 | Cash Out Hook | `IJBCashOutHook.afterCashOutRecordedWith` | JBMultiTerminal |
-| Split Hook | `IJBSplitHook.processSplitWith` | JBMultiTerminal, JBController |
+| Split Hook | `IJBSplitHook.processSplitWith` | JBMultiTerminal, JBController (try-catch; reverts emit `SplitHookReverted`) |
 | Approval Hook | `IJBRulesetApprovalHook.approvalStatusOf` | JBRulesets |
 
 ## Dependencies

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,34 @@ 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.8 JBDirectory -- ADD_TERMINALS Permission on Implicit Addition
+
+`setPrimaryTerminalOf` now requires the `ADD_TERMINALS` permission when the specified terminal is not already in the project's terminal list. Previously, `setPrimaryTerminalOf` would implicitly add the terminal to the project's terminal list without any permission check beyond `SET_PRIMARY_TERMINAL`. Now, if `isTerminalOf(projectId, terminal)` returns false, the caller (or the account they're acting on behalf of) must also hold the `ADD_TERMINALS` permission for the project. Terminals already in the list are unaffected.
+
+### 0.9 JBController -- Split Hook Try-Catch
+
+`_sendReservedTokensToSplitsOf` now wraps the `split.hook.processSplitWith(...)` call in a try-catch. If a split hook reverts, the tokens already transferred to the hook remain with the hook (they were transferred via `safeTransfer` before the `processSplitWith` call), and the controller emits a `SplitHookReverted(projectId, hook, reason)` event instead of propagating the revert. This prevents a single reverting split hook from blocking the entire reserved token distribution. A new event `SplitHookReverted` was added to `IJBController`.
+
+### 0.10 JBChainlinkV3SequencerPriceFeed -- Sequencer Down Check
+
+The sequencer status check changed from `answer == 1` to `answer != 0`. The Chainlink sequencer uptime feed returns `0` for "up" and `1` for "down", but may return other non-zero values in future feed versions. The new check treats any non-zero answer as sequencer-down, which is the safer default.
+
+### 0.11 JBMultiTerminal -- forceApprove
+
+`_beforeSendFor` now uses `forceApprove` (from OpenZeppelin's `SafeERC20`) instead of `safeIncreaseAllowance` when setting token allowances for outbound ERC-20 transfers. `safeIncreaseAllowance` could fail if a previous allowance was partially consumed and a non-standard token (e.g., USDT) requires the allowance to be zero before setting a new value. `forceApprove` resets the allowance to zero first if needed, then sets it to the desired amount.
+
+### 0.12 JBChainlinkV3PriceFeed -- answeredInRound Check
+
+`currentUnitPrice` now checks `answeredInRound < roundId` after retrieving `latestRoundData()`. If `answeredInRound` is less than `roundId`, the answer was carried over from a previous round and the current round is incomplete. This reverts with `JBChainlinkV3PriceFeed_IncompleteRound()`, complementing the existing `updatedAt == 0` check to catch additional incomplete round scenarios.
+
+### 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
@@ -158,6 +186,7 @@ Parameters changed from `memory` to `calldata` for gas efficiency.
 |----------|-------|
 | `IJBTokens` | `SetTokenMetadata(uint256 indexed projectId, string name, string symbol, address caller)` |
 | `IJBPermitTerminal` | `Permit2AllowanceFailed(address indexed token, address indexed owner, bytes reason)` |
+| `IJBController` | `SplitHookReverted(uint256 indexed projectId, address hook, bytes reason)` |
 
 ### 2.3 New Errors
 
@@ -182,6 +211,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.
@@ -313,6 +349,7 @@ No changes.
 | **Migration lifecycle** | `afterReceiveMigrationFrom` added — called by directory after migration completes (validates caller is directory). |
 | **`launchRulesetsFor` permission** | Changed from `QUEUE_RULESETS` to `LAUNCH_RULESETS`. |
 | **Split token transfer assertion** | `assert(allowance == 0)` replaced with explicit `revert JBController_TerminalTokensNotTransferred()`. |
+| **Split hook try-catch** | `processSplitWith` in `_sendReservedTokensToSplitsOf` is now wrapped in a try-catch. A reverting split hook emits `SplitHookReverted` instead of propagating. Transferred tokens stay with the hook. |
 | **Code organization** | External views moved after external transactions. Internal views moved to end of file. |
 
 ### 8.2 JBMultiTerminal
@@ -326,6 +363,7 @@ No changes.
 | **Split payout documentation** | Failed split payouts documented as consuming payout limit by design. |
 | **Fee-free cashout bypass prevention** | New `_feeFreeSurplusOf` mapping tracks cumulative fee-free intra-terminal payouts per project/token. Capped at remaining balance after outflows including non-zero-tax/feeless cashouts (non-fee-free funds leave first). During zero-tax cashouts, fees are charged up to this tracked amount (then decremented). Cleared on migration. See Section 0.2. |
 | **beneficiaryIsFeeless passthrough** | `cashOutTokensOf` now passes `_isFeeless(beneficiary)` to `recordCashOutFor`, which forwards it to data hooks via `JBBeforeCashOutRecordedContext.beneficiaryIsFeeless`. |
+| **forceApprove** | `_beforeSendFor` now uses `forceApprove` instead of `safeIncreaseAllowance` for outbound ERC-20 token approvals, avoiding reverts on tokens (e.g. USDT) that require zero allowance before re-approval. |
 
 ### 8.3 JBRulesets
 
@@ -341,6 +379,7 @@ No changes.
 | Change | Description |
 |--------|-------------|
 | **Migration ordering** | `setControllerOf` now calls `migrate()` on the old controller BEFORE updating `controllerOf` in storage (so `migrate()` runs while the directory still points to the old controller). After updating storage, it calls `afterReceiveMigrationFrom` on the new controller. |
+| **ADD_TERMINALS permission on implicit addition** | `setPrimaryTerminalOf` now requires the `ADD_TERMINALS` permission when the terminal is not already in the project's terminal list. Previously, implicit addition had no permission check beyond `SET_PRIMARY_TERMINAL`. |
 
 ### 8.5 JBSplits
 
@@ -365,6 +404,7 @@ No changes.
 | Change | Description |
 |--------|-------------|
 | **Incomplete round check order** | The check for `updatedAt == 0` (incomplete round) now runs BEFORE the stale price check, avoiding false stale errors on incomplete rounds. |
+| **answeredInRound check** | `currentUnitPrice` now checks `answeredInRound < roundId` and reverts with `IncompleteRound` if the answer was carried over from a previous round. |
 
 ### 8.9 JBChainlinkV3SequencerPriceFeed
 
@@ -372,6 +412,7 @@ No changes.
 |--------|-------------|
 | **Typo fix** | Error parameter `gradePeriodTime` corrected to `gracePeriodTime` in `JBChainlinkV3SequencerPriceFeed_SequencerDown`. |
 | **Threshold docs** | Constructor parameter `threshold` documentation corrected from "blocks" to "seconds". |
+| **Sequencer down check** | Changed `answer == 1` to `answer != 0` in the sequencer uptime check. Any non-zero answer is now treated as sequencer-down, which is the safer default for future Chainlink feed versions. |
 
 ### 8.10 Solidity Version
 

package/README.md

@@ -147,7 +147,7 @@ graph TD;
 | Contract | Description |
 |----------|-------------|
 | `JBERC20` | Cloneable ERC-20 with ERC20Votes and ERC20Permit. Deployed by `JBTokens` via `Clones.clone()`. Owned by `JBTokens`. Name and symbol can be updated by the project owner via `JBController.setTokenMetadataOf`. |
-| `JBChainlinkV3PriceFeed` | `IJBPriceFeed` backed by a Chainlink `AggregatorV3Interface` with staleness threshold. Rejects negative/zero prices and incomplete rounds. |
+| `JBChainlinkV3PriceFeed` | `IJBPriceFeed` backed by a Chainlink `AggregatorV3Interface` with staleness threshold. Rejects negative/zero prices, incomplete rounds (`updatedAt == 0`), and stale answers carried from previous rounds (`answeredInRound < roundId`). |
 | `JBChainlinkV3SequencerPriceFeed` | Extends `JBChainlinkV3PriceFeed` with L2 sequencer uptime validation and grace period for Optimism/Arbitrum. |
 | `JBMatchingPriceFeed` | Returns 1:1 price (e.g., ETH/NATIVE_TOKEN on applicable chains). Lives in `src/periphery/`. |
 
@@ -196,7 +196,7 @@ This section summarizes known risks and design trade-offs. None of these are unm
 
 ### Reentrancy
 
-The protocol does not use an explicit `ReentrancyGuard`. Instead, it relies on **state ordering**: all storage writes (balance updates, token mints/burns, payout limit usage) are completed before any external calls (hooks, split payouts, fee processing). This means re-entering a function sees already-updated state, preventing double-spends and double-payouts. The `try-catch` pattern around external calls ensures that hook failures do not leave the protocol in an inconsistent state -- failed calls return funds to the project balance.
+The protocol does not use an explicit `ReentrancyGuard`. Instead, it relies on **state ordering**: all storage writes (balance updates, token mints/burns, payout limit usage) are completed before any external calls (hooks, split payouts, fee processing). This means re-entering a function sees already-updated state, preventing double-spends and double-payouts. The `try-catch` pattern around external calls ensures that hook failures do not leave the protocol in an inconsistent state -- failed calls return funds to the project balance. This includes reserved token split hooks: `processSplitWith` is wrapped in try-catch, and a reverting hook emits `SplitHookReverted` instead of blocking distribution.
 
 ### Unbounded Arrays
 

package/RISKS.md

@@ -50,15 +50,16 @@ No `ReentrancyGuard` is used. The system relies on state ordering and the `Inade
 | `_cashOutTokensOf` | `STORE.recordCashOutFor` (balance decremented), `controller.burnTokensOf` (tokens burned), `_transferFrom` (beneficiary paid) | Cash out hooks via `_fulfillCashOutHookSpecificationsFor`, then `_takeFeeFrom` | MEDIUM -- beneficiary receives funds before hooks execute; hooks run before fees are taken |
 | `executePayout` | `STORE.recordPayoutFor` already consumed payout limit | `split.hook.processSplitWith`, `terminal.pay/addToBalance` | MEDIUM -- split hook receives funds and can re-enter; payout limit already consumed prevents double-payout |
 | `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 |
+| `_sendReservedTokensToSplitsOf` | `pendingReservedTokenBalanceOf` zeroed, tokens minted to controller | Split hooks (try-catch), terminal payments | LOW -- pending balance cleared before minting prevents double-distribution. Split hook `processSplitWith` is wrapped in try-catch; a reverting hook emits `SplitHookReverted` but does not block distribution. Tokens already transferred to the hook via `safeTransfer` remain with the hook. |
 | `_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.
+- **Reserved token split hook -> re-entry**: During `_sendReservedTokensToSplitsOf`, a split hook's `processSplitWith` is now wrapped in try-catch. A reverting hook emits `SplitHookReverted` and does not block distribution. Tokens transferred to the hook before the call remain with it. A hook that re-enters during `processSplitWith` sees post-mint state (pending reserved balance already zeroed).
 - **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
@@ -74,10 +75,14 @@ No `ReentrancyGuard` is used. The system relies on state ordering and the `Inade
 - **Empty permission arrays pass `hasPermissions`.** By design (vacuous truth). Any caller that expects "the operator has at least one of these permissions" must validate the array is non-empty.
 - **`OMNICHAIN_RULESET_OPERATOR` bypass.** This immutable address can `launchRulesetsFor`, `queueRulesetsOf`, and set terminals for any project without owner permission. The trust assumption is that this operator only queues rulesets that the omnichain deployer's logic permits. If this address is an EOA or an upgradeable contract, it is a single point of failure for all projects.
 
+### Directory Terminal Addition
+
+- **`setPrimaryTerminalOf` implicit terminal addition** now requires the `ADD_TERMINALS` permission when the terminal is not already in the project's terminal list. This closes a gap where `SET_PRIMARY_TERMINAL` alone could silently add a new terminal without the `ADD_TERMINALS` permission check. If the terminal is already in the list, no additional permission is needed.
+
 ### 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
@@ -100,8 +105,8 @@ No `ReentrancyGuard` is used. The system relies on state ordering and the `Inade
 
 ### Price Feed Reverts
 
-- If a Chainlink feed is stale beyond its threshold, `JBChainlinkV3PriceFeed` reverts. This blocks all multi-currency operations for projects using that feed: `pay`, `cashOutTokensOf`, `sendPayoutsOf`, `useAllowanceOf`.
-- L2 sequencer downtime triggers `JBChainlinkV3SequencerPriceFeed` to revert during downtime + grace period.
+- If a Chainlink feed is stale beyond its threshold, `JBChainlinkV3PriceFeed` reverts. This blocks all multi-currency operations for projects using that feed: `pay`, `cashOutTokensOf`, `sendPayoutsOf`, `useAllowanceOf`. The feed also reverts with `IncompleteRound` when `answeredInRound < roundId` (answer carried from a previous round).
+- L2 sequencer downtime triggers `JBChainlinkV3SequencerPriceFeed` to revert during downtime + grace period. The sequencer check uses `answer != 0` (any non-zero value = down), which is forward-compatible with future Chainlink feed versions that may use values other than `1` for the down state.
 - Single-currency projects (where `amount.currency == ruleset.baseCurrency()`) are unaffected.
 - Price feeds are immutable once set in `JBPrices` -- a broken feed cannot be replaced.
 

package/SKILLS.md

@@ -21,8 +21,8 @@ The core Juicebox V6 protocol on EVM: a modular system for launching treasury-ba
 | `JBPrices` | Price feed registry with project-specific and protocol-wide default feeds. Immutable once set. |
 | `JBERC20` | Cloneable ERC-20 with Votes + Permit. Owned by `JBTokens`. Deployed via `Clones.clone()`. |
 | `JBFeelessAddresses` | Allowlist for fee-exempt addresses. |
-| `JBChainlinkV3PriceFeed` | Chainlink AggregatorV3 price feed with staleness threshold. Rejects negative/zero prices. |
-| `JBChainlinkV3SequencerPriceFeed` | L2 sequencer-aware Chainlink feed (Optimism/Arbitrum) with grace period after restart. |
+| `JBChainlinkV3PriceFeed` | Chainlink AggregatorV3 price feed with staleness threshold. Rejects negative/zero prices, incomplete rounds (`updatedAt == 0`), and stale answers carried from previous rounds (`answeredInRound < roundId`). |
+| `JBChainlinkV3SequencerPriceFeed` | L2 sequencer-aware Chainlink feed (Optimism/Arbitrum) with grace period after restart. Treats any non-zero sequencer answer as down (`answer != 0`). |
 | `JBDeadline` | Approval hook: rejects rulesets queued within `DURATION` seconds of start. Ships as `JBDeadline3Hours`, `JBDeadline1Day`, `JBDeadline3Days`, `JBDeadline7Days`. |
 | `JBMatchingPriceFeed` | Always returns 1:1. For equivalent currencies (e.g. ETH/NATIVE_TOKEN). |
 
@@ -121,7 +121,7 @@ The core Juicebox V6 protocol on EVM: a modular system for launching treasury-ba
 | `isTerminalOf(uint256 projectId, IJBTerminal terminal)` | Checks if a terminal belongs to a project. |
 | `setControllerOf(uint256 projectId, IERC165 controller)` | Sets the project's controller. |
 | `setTerminalsOf(uint256 projectId, IJBTerminal[] terminals)` | Sets the project's terminals. |
-| `setPrimaryTerminalOf(uint256 projectId, address token, IJBTerminal terminal)` | Sets the primary terminal for a token. |
+| `setPrimaryTerminalOf(uint256 projectId, address token, IJBTerminal terminal)` | Sets the primary terminal for a token. Requires `ADD_TERMINALS` permission if the terminal is not already in the project's terminal list (implicit addition). |
 | `setIsAllowedToSetFirstController(address addr, bool flag)` | Allows/disallows an address to set a project's first controller. Owner-only. |
 
 ### JBPrices
@@ -288,7 +288,7 @@ Quick-reference for the most common `JBPermissionIds` values (from `@bananapus/p
 | `13` | `TRANSFER_CREDITS` | `JBController.transferCreditsFrom` |
 | `14` | `SET_CONTROLLER` | `JBDirectory.setControllerOf` |
 | `15` | `SET_TERMINALS` | `JBDirectory.setTerminalsOf` (can remove primary terminal) |
-| `16` | `SET_PRIMARY_TERMINAL` | `JBDirectory.setPrimaryTerminalOf` |
+| `16` | `SET_PRIMARY_TERMINAL` | `JBDirectory.setPrimaryTerminalOf` (also requires `ADD_TERMINALS` if the terminal is not already in the project's list) |
 | `17` | `USE_ALLOWANCE` | `JBMultiTerminal.useAllowanceOf` |
 | `18` | `SET_SPLIT_GROUPS` | `JBController.setSplitGroupsOf` |
 | `19` | `ADD_PRICE_FEED` | `JBController.addPriceFeedFor` |
@@ -359,6 +359,7 @@ The most important events for indexing and off-chain monitoring. Indexed params
 | `BurnTokens` | `IJBController` | `holder*`, `projectId*`, `tokenCount` |
 | `SendReservedTokensToSplits` | `IJBController` | `rulesetId*`, `rulesetCycleNumber*`, `projectId*`, `owner`, `tokenCount`, `leftoverAmount` |
 | `SendReservedTokensToSplit` | `IJBController` | `projectId*`, `rulesetId*`, `groupId*`, `split`, `tokenCount` |
+| `SplitHookReverted` | `IJBController` | `projectId*`, `hook`, `reason` |
 | `LaunchProject` | `IJBController` | `rulesetId`, `projectId`, `projectUri` |
 | `QueueRulesets` | `IJBController` | `rulesetId`, `projectId` |
 | `DeployERC20` | `IJBController` | `projectId*`, `deployer*`, `salt`, `saltHash`, `caller` |

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.29",
   "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/script/DeployPeriphery.s.sol

@@ -147,31 +147,34 @@ contract DeployPeriphery is Script, Sphinx {
         }
         require(address(feed) != address(0), "Invalid price feed");
 
-        core.prices
+        try core.prices
             .addPriceFeedFor({
                 projectId: 0,
                 pricingCurrency: JBCurrencyIds.USD,
                 unitCurrency: uint32(uint160(JBConstants.NATIVE_TOKEN)),
                 feed: feed
-            });
+            }) {}
+            catch {}
 
         // WARN: We are using the same price feed as the native token for the USD price feed. Which is only valid on
         // chains where Ether is the native asset. We *NEED* to update this when we deploy to a non-ether chain!
-        core.prices
+        try core.prices
             .addPriceFeedFor({
                 projectId: 0, pricingCurrency: JBCurrencyIds.USD, unitCurrency: JBCurrencyIds.ETH, feed: feed
-            });
+            }) {}
+            catch {}
 
         // If the native asset for this chain is ether, then the conversion from native asset to ether is 1:1.
         // NOTE: We need to refactor this the moment we add a chain where its native token is *NOT* ether.
         // As otherwise prices for the `NATIVE_TOKEN` will be incorrect!
-        core.prices
+        try core.prices
             .addPriceFeedFor({
                 projectId: 0,
                 pricingCurrency: JBCurrencyIds.ETH,
                 unitCurrency: uint32(uint160(JBConstants.NATIVE_TOKEN)),
                 feed: matchingPriceFeed
-            });
+            }) {}
+            catch {}
 
         // Deploy the USDC/USD price feed.
         _deployUSDCFeed(L2GracePeriod);
@@ -279,14 +282,12 @@ contract DeployPeriphery is Script, Sphinx {
         require(usdc.code.length > 0, "Invalid USDC address");
         require(address(usdcFeed) != address(0), "Invalid USDC price feed");
 
-        core.prices
+        // forge-lint: disable-next-line(unsafe-typecast)
+        try core.prices
             .addPriceFeedFor({
-                projectId: 0,
-                pricingCurrency: JBCurrencyIds.USD,
-                // forge-lint: disable-next-line(unsafe-typecast)
-                unitCurrency: uint32(uint160(usdc)),
-                feed: usdcFeed
-            });
+                projectId: 0, pricingCurrency: JBCurrencyIds.USD, unitCurrency: uint32(uint160(usdc)), feed: usdcFeed
+            }) {}
+            catch {}
     }
 
     /// @dev This helper predicts addresses using the Arachnid CREATE2 deployer, but actual deployments go through

package/src/JBChainlinkV3PriceFeed.sol

@@ -50,12 +50,15 @@ contract JBChainlinkV3PriceFeed is IJBPriceFeed {
     function currentUnitPrice(uint256 decimals) public view virtual override returns (uint256) {
         // Get the latest round information from the feed.
         // slither-disable-next-line unused-return
-        (, int256 price,, uint256 updatedAt,) = FEED.latestRoundData();
+        (uint80 roundId, int256 price,, uint256 updatedAt, uint80 answeredInRound) = FEED.latestRoundData();
 
         // Make sure the round is finished (check before stale price to avoid false stale on incomplete rounds).
         // slither-disable-next-line incorrect-equality
         if (updatedAt == 0) revert JBChainlinkV3PriceFeed_IncompleteRound();
 
+        // Make sure the answer was provided in the current round.
+        if (answeredInRound < roundId) revert JBChainlinkV3PriceFeed_IncompleteRound();
+
         // Make sure the price's update threshold is met.
         if (block.timestamp > THRESHOLD + updatedAt) {
             revert JBChainlinkV3PriceFeed_StalePrice(block.timestamp, THRESHOLD, updatedAt);

package/src/JBChainlinkV3SequencerPriceFeed.sol

@@ -64,7 +64,7 @@ contract JBChainlinkV3SequencerPriceFeed is JBChainlinkV3PriceFeed {
         if (startedAt == 0) revert JBChainlinkV3SequencerPriceFeed_InvalidRound();
 
         // Revert if sequencer has too recently restarted or is currently down.
-        if (block.timestamp <= GRACE_PERIOD_TIME + startedAt || answer == 1) {
+        if (block.timestamp <= GRACE_PERIOD_TIME + startedAt || answer != 0) {
             revert JBChainlinkV3SequencerPriceFeed_SequencerDownOrRestarting(
                 block.timestamp, GRACE_PERIOD_TIME, startedAt
             );

package/src/JBController.sol

@@ -1024,7 +1024,7 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
                     });
 
                     // slither-disable-next-line reentrancy-events
-                    split.hook
+                    try split.hook
                         .processSplitWith(
                             JBSplitHookContext({
                                 token: address(token),
@@ -1034,7 +1034,11 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
                                 groupId: groupId,
                                 split: split
                             })
-                        );
+                        ) {}
+                    catch (bytes memory reason) {
+                        // If the hook reverts, the tokens already transferred to it stay with the hook.
+                        emit SplitHookReverted({projectId: projectId, hook: address(split.hook), reason: reason});
+                    }
                     // If the split has a project ID, try to pay the project. If that fails, pay the beneficiary.
                 } else {
                     // Pay the project using the split's beneficiary if one was provided. Otherwise, use the message

package/src/JBDirectory.sol

@@ -185,6 +185,13 @@ contract JBDirectory is JBPermissioned, Ownable, IJBDirectory {
             revert JBDirectory_TokenNotAccepted(projectId, token, terminal);
         }
 
+        // If the terminal is not already in the project's terminal list, require ADD_TERMINALS permission.
+        if (!isTerminalOf({projectId: projectId, terminal: terminal})) {
+            _requirePermissionFrom({
+                account: PROJECTS.ownerOf(projectId), projectId: projectId, permissionId: JBPermissionIds.ADD_TERMINALS
+            });
+        }
+
         // Implicit terminal addition is by design. A primary terminal must be in the terminals list;
         // implicit addition avoids requiring a separate addTerminalsOf call.
         _addTerminalIfNeeded({projectId: projectId, terminal: terminal});

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;
 
@@ -397,6 +407,14 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
                     beneficiary: beneficiary,
                     metadata: metadata
                 });
+
+                // Cap fee-free surplus at remaining balance.
+                // Why: _feeFreeSurplusOf was incremented by the full netPayoutAmount above, but if the
+                // destination project's data hook forwarded part of the payment to pay hooks, the store
+                // only recorded a partial balance increase. Without this cap, _feeFreeSurplusOf can exceed
+                // STORE.balanceOf, causing users to be overcharged fees on zero-tax cashouts.
+                // slither-disable-next-line reentrancy-eth
+                _capFeeFreeSurplus({projectId: split.projectId, token: token});
             }
         } else {
             // If there's a beneficiary, send the funds directly to the beneficiary.
@@ -492,12 +510,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 +526,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 +620,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.
@@ -1047,7 +1083,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         if (token == JBConstants.NATIVE_TOKEN) return amount;
 
         // Otherwise, set the allowance, and the payValue should be 0.
-        IERC20(token).safeIncreaseAllowance({spender: to, value: amount});
+        IERC20(token).forceApprove({spender: to, value: amount});
         return 0;
     }
 
@@ -1113,8 +1149,6 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
                     // Non-zero tax: fees apply to the full reclaim amount.
                     amountEligibleForFees += reclaimAmount;
                     reclaimAmount -= JBFees.feeAmountFrom({amountBeforeFee: reclaimAmount, feePercent: FEE});
-                    // Cap fee-free surplus at remaining balance (non-fee-free funds leave first).
-                    _reduceFeeFreeSurplus({projectId: projectId, token: tokenToReclaim});
                 } else {
                     // Zero tax: fees apply only up to the fee-free surplus (round-trip prevention).
                     uint256 feeFreeSurplus = _feeFreeSurplusOf[projectId][tokenToReclaim];
@@ -1125,9 +1159,6 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
                         reclaimAmount -= JBFees.feeAmountFrom({amountBeforeFee: feeableAmount, feePercent: FEE});
                     }
                 }
-            } else {
-                // Feeless beneficiary: fee logic skipped, but still cap fee-free surplus at remaining balance.
-                _reduceFeeFreeSurplus({projectId: projectId, token: tokenToReclaim});
             }
 
             // Subtract the fee from the reclaim amount.
@@ -1154,6 +1185,16 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             });
         }
 
+        // Cap fee-free surplus at remaining balance.
+        // Why: this single call replaces per-branch calls so that EVERY cashout path (non-zero tax,
+        // zero tax, and feeless beneficiary) gets the cap. Without it, the zero-tax path would use
+        // a stale _feeFreeSurplusOf that may exceed STORE.balanceOf (e.g. if pay hooks reduced the
+        // balance during a prior inbound payout), overcharging fees on round-trip prevention.
+        // Placed after hook fulfillment so any further balance reductions from cashout hooks are
+        // also accounted for.
+        // slither-disable-next-line reentrancy-eth
+        _capFeeFreeSurplus({projectId: projectId, token: tokenToReclaim});
+
         // Take the fee from all outbound reclaimings.
         if (amountEligibleForFees != 0) {
             _takeFeeFrom({
@@ -1674,7 +1715,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             STORE.recordPayoutFor({projectId: projectId, token: token, amount: amount, currency: currency});
 
         // Cap fee-free surplus at remaining balance. Non-fee-free funds leave first.
-        _reduceFeeFreeSurplus({projectId: projectId, token: token});
+        _capFeeFreeSurplus({projectId: projectId, token: token});
 
         // Get a reference to the project's owner.
         // The owner will receive tokens minted by paying the platform fee and receive any leftover funds not sent to
@@ -1875,7 +1916,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             STORE.recordUsedAllowanceOf({projectId: projectId, token: token, amount: amount, currency: currency});
 
         // Cap fee-free surplus at remaining balance. Non-fee-free funds leave first.
-        _reduceFeeFreeSurplus({projectId: projectId, token: token});
+        _capFeeFreeSurplus({projectId: projectId, token: token});
 
         // Take a fee from the `amountPaidOut`, if needed.
         // The net amount is the final amount withdrawn after the fee has been taken.
@@ -1917,11 +1958,11 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     /// and then cashing out without incurring fees.
     /// @param projectId The ID of the project.
     /// @param token The token whose fee-free surplus to cap.
-    function _reduceFeeFreeSurplus(uint256 projectId, address token) internal {
+    function _capFeeFreeSurplus(uint256 projectId, address token) internal {
         // Get the current fee-free surplus for this project/token pair.
         uint256 feeFreeSurplus = _feeFreeSurplusOf[projectId][token];
 
-        // Nothing to reduce if there's no fee-free surplus tracked.
+        // Nothing to cap if there's no fee-free surplus tracked.
         if (feeFreeSurplus == 0) return;
 
         // Get the project's remaining balance (already decremented by the store's record call).