@bananapus/core-v6 0.0.48 → 0.0.51

package/src/JBMultiTerminal.sol

@@ -28,8 +28,10 @@ import {IJBSplits} from "./interfaces/IJBSplits.sol";
 import {IJBTerminal} from "./interfaces/IJBTerminal.sol";
 import {IJBTerminalStore} from "./interfaces/IJBTerminalStore.sol";
 import {IJBTokens} from "./interfaces/IJBTokens.sol";
+import {JBCashOutHookSpecsLib} from "./libraries/JBCashOutHookSpecsLib.sol";
 import {JBConstants} from "./libraries/JBConstants.sol";
 import {JBFees} from "./libraries/JBFees.sol";
+import {JBHeldFeesLib} from "./libraries/JBHeldFeesLib.sol";
 import {JBMetadataResolver} from "./libraries/JBMetadataResolver.sol";
 import {JBPayoutSplitGroupLib} from "./libraries/JBPayoutSplitGroupLib.sol";
 import {JBRulesetMetadataResolver} from "./libraries/JBRulesetMetadataResolver.sol";
@@ -40,6 +42,7 @@ import {JBCashOutHookSpecification} from "./structs/JBCashOutHookSpecification.s
 import {JBFee} from "./structs/JBFee.sol";
 import {JBPayHookSpecification} from "./structs/JBPayHookSpecification.sol";
 import {JBRuleset} from "./structs/JBRuleset.sol";
+import {JBRulesetMetadata} from "./structs/JBRulesetMetadata.sol";
 import {JBSingleAllowance} from "./structs/JBSingleAllowance.sol";
 import {JBSplit} from "./structs/JBSplit.sol";
 import {JBSplitHookContext} from "./structs/JBSplitHookContext.sol";
@@ -63,6 +66,9 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
+    error JBMultiTerminal_BeneficiaryProjectFeeFreeInflowsPaused(uint256 projectId);
+    error JBMultiTerminal_BeneficiaryProjectHasNoAccountingContexts(uint256 projectId);
+    error JBMultiTerminal_BeneficiaryProjectNotPaid(uint256 projectId);
     error JBMultiTerminal_FeeTerminalNotFound(address token);
     error JBMultiTerminal_MintNotAllowed(uint256 projectId, uint256 splitProjectId, address terminal);
     error JBMultiTerminal_NoMsgValueAllowed(uint256 value);
@@ -81,16 +87,14 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
 
     /// @notice This terminal's fee (as a fraction out of `JBConstants.MAX_FEE`).
     /// @dev Fees are charged on payouts to addresses and surplus allowance usage, as well as cash outs while the
-    /// cash out tax rate is less than 100%.
-    uint256 public constant override FEE = 25; // 2.5%
+    /// cash out tax rate is less than 100%. Re-exports `JBConstants.FEE` so external callers can read it through
+    /// the `IJBFeeTerminal` interface.
+    uint256 public constant override FEE = JBConstants.FEE;
 
     //*********************************************************************//
     // ------------------------ internal constants ----------------------- //
     //*********************************************************************//
 
-    /// @notice Project ID #1 receives fees. It should be the first project launched during the deployment process.
-    uint256 internal constant _FEE_BENEFICIARY_PROJECT_ID = 1;
-
     /// @notice The number of seconds fees can be held for.
     uint256 internal constant _FEE_HOLDING_SECONDS = 2_419_200; // 28 days
 
@@ -220,6 +224,78 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         }
     }
 
+    /// @notice Atomically cash out `holder`'s tokens of `projectId` and add the reclaim to
+    /// `beneficiaryProjectId`'s balance (no project tokens minted on the destination side).
+    /// @dev Equivalent to calling `cashOutTokensOf` followed by `addToBalanceOf` on the destination project,
+    /// except the source-side cash out fee is skipped. The equivalent fee is bound on the destination project's
+    /// side instead: `_feeFreeSurplusOf[beneficiaryProjectId]` is credited by the first of the destination
+    /// project's accounting contexts on this terminal whose balance grows during the routing.
+    /// @dev The destination terminal is `DIRECTORY.primaryTerminalOf(beneficiaryProjectId, tokenToReclaim)` —
+    /// which may itself be a router that swaps before adding to balance.
+    /// @dev Held-fee return on the destination side is hardcoded to `false`. This entrypoint is for cross-project
+    /// balance top-ups only, not for unlocking the destination's held fees. Callers that want to combine
+    /// cash-out → add-to-balance with `shouldReturnHeldFees: true` must do it explicitly via two separate calls.
+    /// @dev The destination project's current ruleset can set `pauseCrossProjectFeeFreeInflows` to opt out — the
+    /// call then reverts. If no delivery to the destination project lands on this terminal under any of the
+    /// destination project's accounting contexts, the call also reverts so the source-side fee skip never
+    /// becomes a leak.
+    /// @param holder The account whose project tokens are being burned.
+    /// @param projectId The ID of the source project being cashed out from.
+    /// @param cashOutCount The number of source-project tokens to burn, as a fixed point number with 18 decimals.
+    /// @param tokenToReclaim The terminal token reclaimed from the source project's surplus.
+    /// @param beneficiaryProjectId The destination project receiving the reclaim.
+    /// @param cashOutMetadata Bytes forwarded to the source project's data hook and any cashout hook specifications.
+    /// @param addToBalanceMetadata Bytes forwarded to the destination project's `addToBalanceOf` event.
+    /// @return reclaimAmount The gross reclaim amount returned by the store.
+    function addToBalanceAfterCashOutTokensOf(
+        address holder,
+        uint256 projectId,
+        uint256 cashOutCount,
+        address tokenToReclaim,
+        uint256 beneficiaryProjectId,
+        bytes calldata cashOutMetadata,
+        bytes calldata addToBalanceMetadata
+    )
+        external
+        override
+        returns (uint256 reclaimAmount)
+    {
+        _requireCashOutPermissionFrom({holder: holder, projectId: projectId});
+        _requireBeneficiaryAcceptsFeeFreeInflows(beneficiaryProjectId);
+
+        // Burn source-project tokens, run cashout-side hooks, take any hook fees, and cap source fee-free.
+        // No separate destination beneficiary exists — the caller is the only address attached to this flow,
+        // used as the `CashOutTokens` event slot and credited any hook-fee project tokens.
+        reclaimAmount = _executeCrossProjectCashOut({
+            holder: holder,
+            projectId: projectId,
+            cashOutCount: cashOutCount,
+            tokenToReclaim: tokenToReclaim,
+            beneficiary: _msgSender(),
+            cashOutMetadata: cashOutMetadata
+        });
+
+        // Nothing to route if the data hook returned zero reclaim.
+        if (reclaimAmount == 0) return 0;
+
+        // Route the reclaim to B's primary terminal as an `addToBalanceOf`, then credit B's fee-free surplus
+        // by the delivery delta. `_efficientAddToBalance` handles same-terminal vs cross-terminal and
+        // hardcodes `shouldReturnHeldFees: false` — this entrypoint cannot unlock B's held fees.
+        IJBTerminal destinationTerminal = _resolveBeneficiaryTerminal(beneficiaryProjectId, tokenToReclaim);
+        (JBAccountingContext[] memory contexts, uint256[] memory balancesBefore) =
+            _snapshotBeneficiaryContextBalances(beneficiaryProjectId);
+
+        _efficientAddToBalance({
+            terminal: destinationTerminal,
+            projectId: beneficiaryProjectId,
+            token: tokenToReclaim,
+            amount: reclaimAmount,
+            metadata: addToBalanceMetadata
+        });
+
+        _creditFirstGrowingBeneficiaryContext(beneficiaryProjectId, contexts, balancesBefore);
+    }
+
     /// @notice Adds funds (terminal tokens) to a project's balance without minting project tokens. Useful for topping
     /// up a project or returning funds. Can also unlock previously held fees by returning them to the project's
     /// balance.
@@ -287,8 +363,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         override
         returns (uint256 reclaimAmount)
     {
-        // Enforce permissions.
-        _requirePermissionFrom({account: holder, projectId: projectId, permissionId: JBPermissionIds.CASH_OUT_TOKENS});
+        _requireCashOutPermissionFrom({holder: holder, projectId: projectId});
 
         reclaimAmount = _cashOutTokensOf({
             holder: holder,
@@ -412,6 +487,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
                     projectId: split.projectId,
                     token: token,
                     amount: netPayoutAmount,
+                    payer: address(this),
                     beneficiary: beneficiary,
                     metadata: metadata
                 });
@@ -473,9 +549,10 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
 
         _efficientPay({
             terminal: feeTerminal,
-            projectId: _FEE_BENEFICIARY_PROJECT_ID,
+            projectId: JBConstants.FEE_BENEFICIARY_PROJECT_ID,
             token: token,
             amount: amount,
+            payer: address(this),
             beneficiary: beneficiary,
             metadata: metadata
         });
@@ -538,7 +615,10 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             // 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({addr: address(to), projectId: projectId}) && projectId != _FEE_BENEFICIARY_PROJECT_ID) {
+            if (
+                !_isFeeless({addr: address(to), projectId: projectId})
+                    && projectId != JBConstants.FEE_BENEFICIARY_PROJECT_ID
+            ) {
                 feeAmount = _takeFeeFrom({
                     projectId: projectId,
                     token: token,
@@ -620,6 +700,71 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         _checkMin({value: beneficiaryTokenCount, min: minReturnedTokens});
     }
 
+    /// @notice Atomically cash out `holder`'s tokens of `projectId` and pay the reclaim into `beneficiaryProjectId`.
+    /// @dev Equivalent to calling `cashOutTokensOf` followed by `pay` on the destination project, except the
+    /// source-side cash out fee is skipped. The equivalent fee is bound on the destination project's side instead:
+    /// `_feeFreeSurplusOf[beneficiaryProjectId]` is credited by the first of the destination project's accounting
+    /// contexts on this terminal whose balance grows during the routing.
+    /// @dev The destination terminal is `DIRECTORY.primaryTerminalOf(beneficiaryProjectId, tokenToReclaim)` —
+    /// which may itself be a router that swaps before paying the destination.
+    /// @dev The destination project's current ruleset can set `pauseCrossProjectFeeFreeInflows` to opt out — the
+    /// call then reverts. If no delivery to the destination project lands on this terminal under any of the
+    /// destination project's accounting contexts, the call also reverts so the source-side fee skip never becomes
+    /// a leak.
+    /// @param holder The account whose project tokens are being burned.
+    /// @param projectId The ID of the source project being cashed out from.
+    /// @param cashOutCount The number of source-project tokens to burn, as a fixed point number with 18 decimals.
+    /// @param tokenToReclaim The terminal token reclaimed from the source project's surplus.
+    /// @param beneficiaryProjectId The destination project receiving the reclaim.
+    /// @param beneficiary The address that receives the newly minted destination-project tokens.
+    /// @param minTokensOut The minimum number of destination-project tokens that must be minted, otherwise revert.
+    /// @param cashOutMetadata Bytes forwarded to the source project's data hook and any cashout hook specifications.
+    /// @param payMetadata Bytes forwarded to the destination project's pay flow.
+    /// @return reclaimAmount The gross reclaim amount returned by the store.
+    /// @return beneficiaryTokenCount The number of destination-project tokens minted to `beneficiary`.
+    function payAfterCashOutTokensOf(
+        address holder,
+        uint256 projectId,
+        uint256 cashOutCount,
+        address tokenToReclaim,
+        uint256 beneficiaryProjectId,
+        address beneficiary,
+        uint256 minTokensOut,
+        bytes calldata cashOutMetadata,
+        bytes calldata payMetadata
+    )
+        external
+        override
+        returns (uint256 reclaimAmount, uint256 beneficiaryTokenCount)
+    {
+        _requireCashOutPermissionFrom({holder: holder, projectId: projectId});
+        _requireBeneficiaryAcceptsFeeFreeInflows(beneficiaryProjectId);
+
+        // Burn source-project tokens, run cashout-side hooks, take any hook fees, and cap source fee-free.
+        reclaimAmount = _executeCrossProjectCashOut({
+            holder: holder,
+            projectId: projectId,
+            cashOutCount: cashOutCount,
+            tokenToReclaim: tokenToReclaim,
+            beneficiary: beneficiary,
+            cashOutMetadata: cashOutMetadata
+        });
+
+        // Nothing to route if the data hook returned zero reclaim.
+        if (reclaimAmount != 0) {
+            beneficiaryTokenCount = _routeReclaimToBeneficiaryProject({
+                tokenToReclaim: tokenToReclaim,
+                reclaimAmount: reclaimAmount,
+                beneficiaryProjectId: beneficiaryProjectId,
+                beneficiary: beneficiary,
+                payMetadata: payMetadata
+            });
+        }
+
+        // Mint floor: how many destination-project tokens were issued for the inbound pay.
+        _checkMin({value: beneficiaryTokenCount, min: minTokensOut});
+    }
+
     /// @notice Processes held fees for a project, sending them to the protocol's fee project. Fees are held for 28 days
     /// after a payout — processing them finalizes the fee payment.
     /// @dev Only processes fees whose `unlockTimestamp` has passed. Stops early if it encounters a still-locked fee.
@@ -631,59 +776,15 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     /// @param token The token to process held fees for.
     /// @param count The number of fees to process.
     function processHeldFeesOf(uint256 projectId, address token, uint256 count) external override {
-        // Keep a reference to the terminal that'll receive the fees.
-        IJBTerminal feeTerminal = _primaryTerminalOf({projectId: _FEE_BENEFICIARY_PROJECT_ID, token: token});
-
-        // Process each fee. Re-read the index and array length from storage each iteration to account for reentrant
-        // calls that may have already advanced the index or cleaned up the array.
-        for (uint256 i; i < count;) {
-            // Read the current index from storage (not a cached value) to prevent reentrancy from
-            // causing double-processing.
-            uint256 currentIndex = _nextHeldFeeIndexOf[projectId][token];
-
-            // If all fees have been processed, break to cleanup.
-            if (currentIndex >= _heldFeesOf[projectId][token].length) break;
-
-            // Keep a reference to the held fee being iterated on.
-            JBFee memory heldFee = _heldFeesOf[projectId][token][currentIndex];
-
-            // Can't process fees that aren't yet unlocked. Fees unlock sequentially in the array, so nothing left to do
-            // if the current fee isn't yet unlocked.
-            // forge-lint: disable-next-line(block-timestamp)
-            if (heldFee.unlockTimestamp > block.timestamp) break;
-
-            // Delete the entry and advance the index *before* the external call. This is intentional:
-            // 1. It prevents reentrancy from reprocessing the same fee.
-            // 2. If `_processFee` fails (try-catch), the fee amount is returned to the project's balance via
-            //    `_recordAddedBalanceFor` — the fee is forgiven rather than retried. This is a deliberate design
-            // choice: projects should not have funds permanently stuck because the fee route is misconfigured or
-            // reverting.
-            //    A `FeeReverted` event is emitted so the forgiveness is observable off-chain.
-            delete _heldFeesOf[projectId][token][currentIndex];
-            _nextHeldFeeIndexOf[projectId][token] = currentIndex + 1;
-
-            // Process the fee.
-            _processFee({
-                projectId: projectId,
-                token: token,
-                amount: _feeAmountFrom(heldFee.amount),
-                beneficiary: heldFee.beneficiary,
-                feeTerminal: feeTerminal,
-                wasHeld: true
-            });
-            unchecked {
-                ++i;
-            }
-        }
-
-        // If all held fees have been processed, reset the array and index entirely to bound storage growth.
-        if (
-            _nextHeldFeeIndexOf[projectId][token] >= _heldFeesOf[projectId][token].length
-                && _heldFeesOf[projectId][token].length > 0
-        ) {
-            delete _heldFeesOf[projectId][token];
-            delete _nextHeldFeeIndexOf[projectId][token];
-        }
+        JBHeldFeesLib.processHeldFees({
+            heldFeesOf: _heldFeesOf,
+            nextHeldFeeIndexOf: _nextHeldFeeIndexOf,
+            directory: DIRECTORY,
+            store: STORE,
+            projectId: projectId,
+            token: token,
+            count: count
+        });
     }
 
     /// @notice Distributes funds from a project's balance to its payout split recipients, up to the current ruleset's
@@ -1154,25 +1255,15 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         // Cache whether the beneficiary is feeless.
         bool beneficiaryIsFeeless = _isFeeless({addr: beneficiary, projectId: projectId});
 
-        {
-            // Cache the controller to avoid a redundant external call (also used inside STORE.recordCashOutFor).
-            IJBController controller = _controllerOf(projectId);
-
-            // Record the cash out.
-            (ruleset, reclaimAmount, cashOutTaxRate, hookSpecifications) = STORE.recordCashOutFor({
-                holder: holder,
-                projectId: projectId,
-                cashOutCount: cashOutCount,
-                tokenToReclaim: tokenToReclaim,
-                beneficiaryIsFeeless: beneficiaryIsFeeless,
-                metadata: metadata
-            });
-
-            // Burn the project tokens.
-            if (cashOutCount != 0) {
-                controller.burnTokensOf({holder: holder, projectId: projectId, tokenCount: cashOutCount, memo: ""});
-            }
-        }
+        // Record the cash out and burn the project tokens.
+        (ruleset, reclaimAmount, cashOutTaxRate, hookSpecifications) = _recordAndBurnCashOut({
+            holder: holder,
+            projectId: projectId,
+            cashOutCount: cashOutCount,
+            tokenToReclaim: tokenToReclaim,
+            beneficiaryIsFeeless: beneficiaryIsFeeless,
+            metadata: metadata
+        });
 
         // Keep a reference to the amount being reclaimed that is subject to fees.
         uint256 amountEligibleForFees;
@@ -1212,7 +1303,8 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         // If the data hook returned cash out hook specifications, fulfill them.
         if (hookSpecifications.length != 0) {
             // Fulfill the cash out hook specifications.
-            amountEligibleForFees += _fulfillCashOutHookSpecificationsFor({
+            amountEligibleForFees += JBCashOutHookSpecsLib.fulfill({
+                feelessAddresses: FEELESS_ADDRESSES,
                 projectId: projectId,
                 holder: holder,
                 cashOutCount: cashOutCount,
@@ -1268,6 +1360,43 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         if (value < min) revert JBMultiTerminal_UnderMin(value, min);
     }
 
+    /// @notice Find the first of B's accounting contexts whose balance grew during the routing, credit
+    /// `_feeFreeSurplusOf[beneficiaryProjectId][token]` by the delta, cap to remaining balance, and return.
+    /// Reverts with `JBMultiTerminal_BeneficiaryProjectNotPaid` if no context grew — without delivery, the
+    /// skipped source-side fee can't be bound and would leak.
+    /// @dev Shared by `_routeReclaimToBeneficiaryProject` and `_routeReclaimAsAddToBalance`. The "first
+    /// growing context wins" rule matches a well-behaved router that picks one of B's tokens (the post-swap
+    /// token) and deposits into that single bucket.
+    /// @param beneficiaryProjectId The destination project.
+    /// @param contexts Accounting contexts captured before the routing.
+    /// @param balancesBefore Pre-routing balances aligned to `contexts` by index.
+    function _creditFirstGrowingBeneficiaryContext(
+        uint256 beneficiaryProjectId,
+        JBAccountingContext[] memory contexts,
+        uint256[] memory balancesBefore
+    )
+        internal
+    {
+        for (uint256 i; i < contexts.length;) {
+            uint256 balanceAfter =
+                STORE.balanceOf({terminal: address(this), projectId: beneficiaryProjectId, token: contexts[i].token});
+
+            if (balanceAfter > balancesBefore[i]) {
+                unchecked {
+                    _feeFreeSurplusOf[beneficiaryProjectId][contexts[i].token] += balanceAfter - balancesBefore[i];
+                }
+                _capFeeFreeSurplus({projectId: beneficiaryProjectId, token: contexts[i].token});
+                return;
+            }
+
+            unchecked {
+                ++i;
+            }
+        }
+
+        revert JBMultiTerminal_BeneficiaryProjectNotPaid(beneficiaryProjectId);
+    }
+
     /// @notice Fund a project either by calling this terminal's internal `addToBalance` function or by calling the
     /// recipient terminal's `addToBalance` function.
     /// @param terminal The terminal on which the project is expecting to receive funds.
@@ -1317,40 +1446,135 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         uint256 projectId,
         address token,
         uint256 amount,
+        address payer,
         address beneficiary,
         bytes memory metadata
     )
         internal
+        returns (uint256 newlyIssuedTokenCount)
     {
         if (terminal == IJBTerminal(address(this))) {
-            _pay({
+            return _pay({
                 projectId: projectId,
                 token: token,
                 amount: amount,
-                payer: address(this),
+                payer: payer,
                 beneficiary: beneficiary,
                 memo: "",
                 metadata: metadata
             });
-        } else {
-            // Trigger any inherited pre-transfer logic.
-            // Keep a reference to the amount that'll be paid as a `msg.value`.
-            uint256 payValue = _beforeTransferTo({to: address(terminal), token: token, amount: amount});
+        }
+
+        // Cross-terminal: standard pre/post transfer + external `pay()`. `minReturnedTokens: 0` because callers
+        // own their own slippage gate (e.g. `_checkMin(beneficiaryTokenCount, minTokensOut)`).
+        uint256 payValue = _beforeTransferTo({to: address(terminal), token: token, amount: amount});
+
+        newlyIssuedTokenCount = terminal.pay{value: payValue}({
+            projectId: projectId,
+            token: token,
+            amount: amount,
+            beneficiary: beneficiary,
+            minReturnedTokens: 0,
+            memo: "",
+            metadata: metadata
+        });
+
+        _afterTransferTo({to: address(terminal), token: token});
+    }
+
+    /// @notice Shared cashout-prep step for both cross-project entrypoints (`_payAfterCashOutTokensOf` and
+    /// `_addToBalanceAfterCashOutTokensOf`). Records the cashout with `beneficiaryIsFeeless: true`, burns the
+    /// holder's project tokens, runs cashout-side hook specs, caps the source's fee-free surplus, and takes
+    /// hook fees. Returns the gross reclaim amount that the caller must then route to the destination project.
+    /// @dev `beneficiary` is recorded in the `CashOutTokens` event and credited any fee-project tokens minted
+    /// from hook fees. For pay it's the user-supplied destination beneficiary; for addToBalance the caller
+    /// passes `_msgSender()` (no separate recipient exists).
+    /// @param holder The account whose source-project tokens are being burned.
+    /// @param projectId The ID of the source project being cashed out from.
+    /// @param cashOutCount The number of source-project tokens to burn.
+    /// @param tokenToReclaim The terminal token reclaimed from the source project's surplus.
+    /// @param beneficiary The address recorded in the event slot and credited any hook-fee project tokens.
+    /// @param cashOutMetadata Bytes forwarded to the source project's data hook and any cashout hook specs.
+    /// @return reclaimAmount The gross reclaim amount returned by the store.
+    function _executeCrossProjectCashOut(
+        address holder,
+        uint256 projectId,
+        uint256 cashOutCount,
+        address tokenToReclaim,
+        address beneficiary,
+        bytes memory cashOutMetadata
+    )
+        internal
+        returns (uint256 reclaimAmount)
+    {
+        // Record the cash out and burn the project tokens. `beneficiaryIsFeeless: true` — the equivalent fee
+        // is bound on the destination side via the `_feeFreeSurplusOf[beneficiaryProjectId]` credit computed
+        // from the delivery delta in the routing step. The external entrypoint reverts if delivery falls short,
+        // so this can never become a leak.
+        (
+            JBRuleset memory ruleset,
+            uint256 _reclaim,
+            uint256 cashOutTaxRate,
+            JBCashOutHookSpecification[] memory hookSpecifications
+        ) = _recordAndBurnCashOut({
+            holder: holder,
+            projectId: projectId,
+            cashOutCount: cashOutCount,
+            tokenToReclaim: tokenToReclaim,
+            beneficiaryIsFeeless: true,
+            metadata: cashOutMetadata
+        });
+        reclaimAmount = _reclaim;
+
+        emit CashOutTokens({
+            rulesetId: ruleset.id,
+            rulesetCycleNumber: ruleset.cycleNumber,
+            projectId: projectId,
+            holder: holder,
+            beneficiary: beneficiary,
+            cashOutCount: cashOutCount,
+            cashOutTaxRate: cashOutTaxRate,
+            reclaimAmount: reclaimAmount,
+            metadata: cashOutMetadata,
+            caller: _msgSender()
+        });
 
-            // Send the fee.
-            // If this terminal's token is ETH, send it in msg.value.
-            terminal.pay{value: payValue}({
+        // Only hook-spec amounts are fee-eligible here; the destination portion is intentionally feeless.
+        uint256 amountEligibleForFees;
+
+        // Hook fees still apply (those funds leave the protocol to external hooks). Hook context sees
+        // `address(this)` as the beneficiary since the terminal is custodying the reclaim mid-flow.
+        if (hookSpecifications.length != 0) {
+            amountEligibleForFees = JBCashOutHookSpecsLib.fulfill({
+                feelessAddresses: FEELESS_ADDRESSES,
                 projectId: projectId,
-                token: token,
-                amount: amount,
-                beneficiary: beneficiary,
-                minReturnedTokens: 0,
-                memo: "",
-                metadata: metadata
+                beneficiaryReclaimAmount: _tokenAmountOf({
+                    projectId: projectId, token: tokenToReclaim, value: reclaimAmount
+                }),
+                holder: holder,
+                cashOutCount: cashOutCount,
+                metadata: cashOutMetadata,
+                ruleset: ruleset,
+                cashOutTaxRate: cashOutTaxRate,
+                beneficiary: payable(address(this)),
+                specifications: hookSpecifications
             });
+        }
 
-            // Revoke the temporary pull allowance now that the recipient terminal call has finished.
-            _afterTransferTo({to: address(terminal), token: token});
+        // Cap the source project's fee-free surplus at remaining balance after the outflow. Same invariant as
+        // `_cashOutTokensOf`: every cashout path keeps `_feeFreeSurplusOf[projectId]` consistent with the
+        // post-outflow balance so later zero-tax cashouts from A don't fee phantom amounts.
+        _capFeeFreeSurplus({projectId: projectId, token: tokenToReclaim});
+
+        // Take the fee on the hook amounts.
+        if (amountEligibleForFees != 0) {
+            _takeFeeFrom({
+                projectId: projectId,
+                token: tokenToReclaim,
+                amount: amountEligibleForFees,
+                beneficiary: beneficiary,
+                shouldHoldFees: false
+            });
         }
     }
 
@@ -1388,106 +1612,6 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         _afterTransferTo({to: address(terminal), token: token});
     }
 
-    /// @notice Fulfills a list of cash out hook specifications.
-    /// @param projectId The ID of the project to cash out from.
-    /// @param beneficiaryReclaimAmount The number of tokens to cash out from the project.
-    /// @param holder The address holding the tokens to cash out.
-    /// @param cashOutCount The number of tokens to cash out.
-    /// @param metadata Bytes to send along to the emitted event and cash out hooks as applicable.
-    /// @param ruleset The ruleset active during this cash out as a `JBRuleset` struct.
-    /// @param cashOutTaxRate The cash out tax rate influencing the reclaim amount, out of
-    /// `JBConstants.MAX_CASH_OUT_TAX_RATE`. @param beneficiary The address which will receive any terminal tokens that
-    /// are cashed out.
-    /// @param specifications The hook specifications to fulfill.
-    /// @return amountEligibleForFees The amount of funds which were allocated to cash out hooks and are eligible for
-    /// fees.
-    function _fulfillCashOutHookSpecificationsFor(
-        uint256 projectId,
-        JBTokenAmount memory beneficiaryReclaimAmount,
-        address holder,
-        uint256 cashOutCount,
-        bytes memory metadata,
-        JBRuleset memory ruleset,
-        uint256 cashOutTaxRate,
-        address payable beneficiary,
-        JBCashOutHookSpecification[] memory specifications
-    )
-        internal
-        returns (uint256 amountEligibleForFees)
-    {
-        // Keep a reference to cash out context for the cash out hooks.
-        JBAfterCashOutRecordedContext memory context = JBAfterCashOutRecordedContext({
-            holder: holder,
-            projectId: projectId,
-            rulesetId: ruleset.id,
-            cashOutCount: cashOutCount,
-            reclaimedAmount: beneficiaryReclaimAmount,
-            forwardedAmount: beneficiaryReclaimAmount,
-            cashOutTaxRate: cashOutTaxRate,
-            beneficiary: beneficiary,
-            hookMetadata: "",
-            cashOutMetadata: metadata
-        });
-
-        for (uint256 i; i < specifications.length;) {
-            // Set the specification being iterated on.
-            JBCashOutHookSpecification memory specification = specifications[i];
-
-            // A noop specification is informational only and doesn't trigger the hook.
-            if (specification.noop) {
-                unchecked {
-                    ++i;
-                }
-                continue;
-            }
-
-            // Get the fee for the specified amount.
-            uint256 specificationAmountFee = _isFeeless({addr: address(specification.hook), projectId: projectId})
-                ? 0
-                : _feeAmountFrom(specification.amount);
-
-            // Add the specification's amount to the amount eligible for fees.
-            if (specificationAmountFee != 0) {
-                amountEligibleForFees += specification.amount;
-                specification.amount -= specificationAmountFee;
-            }
-
-            // Pass the correct token `forwardedAmount` to the hook.
-            context.forwardedAmount = JBTokenAmount({
-                value: specification.amount,
-                token: beneficiaryReclaimAmount.token,
-                decimals: beneficiaryReclaimAmount.decimals,
-                currency: beneficiaryReclaimAmount.currency
-            });
-
-            // Pass the correct metadata from the data hook's specification.
-            context.hookMetadata = specification.metadata;
-
-            // Trigger any inherited pre-transfer logic.
-            // Keep a reference to the amount that'll be paid as a `msg.value`.
-            uint256 payValue = _beforeTransferTo({
-                to: address(specification.hook), token: beneficiaryReclaimAmount.token, amount: specification.amount
-            });
-
-            // Fulfill the specification.
-            specification.hook.afterCashOutRecordedWith{value: payValue}(context);
-
-            // Revoke the temporary pull allowance now that the hook call has finished.
-            _afterTransferTo({to: address(specification.hook), token: beneficiaryReclaimAmount.token});
-
-            emit HookAfterRecordCashOut({
-                hook: specification.hook,
-                context: context,
-                specificationAmount: specification.amount,
-                fee: specificationAmountFee,
-                caller: _msgSender()
-            });
-            unchecked {
-                ++i;
-            }
-        }
-    }
-
     /// @notice Fulfills a list of pay hook specifications.
     /// @param projectId The ID of the project to pay.
     /// @param specifications The pay hook specifications to be fulfilled.
@@ -1583,6 +1707,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     /// applicable.
     /// @param memo A memo to pass along to the emitted event.
     /// @param metadata Bytes to send along to the emitted event, as well as the data hook and pay hook if applicable.
+    /// @return newlyIssuedTokenCount The number of project tokens minted to `beneficiary` as a result of this payment.
     function _pay(
         uint256 projectId,
         address token,
@@ -1593,6 +1718,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         bytes memory metadata
     )
         internal
+        returns (uint256 newlyIssuedTokenCount)
     {
         // Keep a reference to the token amount to forward to the store.
         JBTokenAmount memory tokenAmount = _tokenAmountOf({projectId: projectId, token: token, value: amount});
@@ -1605,9 +1731,6 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             payer: payer, amount: tokenAmount, projectId: projectId, beneficiary: beneficiary, metadata: metadata
         });
 
-        // Keep a reference to the number of tokens issued for the beneficiary.
-        uint256 newlyIssuedTokenCount;
-
         // Mint tokens if needed.
         if (tokenCount != 0) {
             // Set the token count to be the number of tokens minted for the beneficiary instead of the total
@@ -1667,33 +1790,15 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     )
         internal
     {
-        try this.executeProcessFee({
-            projectId: projectId, token: token, amount: amount, beneficiary: beneficiary, feeTerminal: feeTerminal
-        }) {
-            emit ProcessFee({
-                projectId: projectId,
-                token: token,
-                amount: amount,
-                wasHeld: wasHeld,
-                beneficiary: beneficiary,
-                caller: _msgSender()
-            });
-        } catch (bytes memory reason) {
-            // Fee processing failed — intentionally forgive the fee and return the amount to the project.
-            // The held-fee entry (if any) was already deleted by `processHeldFeesOf` before this call, so there is no
-            // retry path. This is by design: a broken or misconfigured fee route should not permanently lock project
-            // funds. The `FeeReverted` event makes this observable off-chain.
-            emit FeeReverted({
-                projectId: projectId,
-                token: token,
-                feeProjectId: _FEE_BENEFICIARY_PROJECT_ID,
-                amount: amount,
-                reason: reason,
-                caller: _msgSender()
-            });
-
-            _recordAddedBalanceFor({projectId: projectId, token: token, amount: amount});
-        }
+        JBHeldFeesLib.processFee({
+            store: STORE,
+            projectId: projectId,
+            token: token,
+            amount: amount,
+            beneficiary: beneficiary,
+            feeTerminal: feeTerminal,
+            wasHeld: wasHeld
+        });
     }
 
     /// @notice Records an added balance for a project.
@@ -1706,6 +1811,74 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         STORE.recordAddedBalanceFor({projectId: projectId, token: token, amount: amount});
     }
 
+    /// @notice Records a cash out in the terminal store and burns the holder's project tokens.
+    /// @dev Shared between `_cashOutTokensOf` and `_payAfterCashOutTokensOf`. The two flows differ in what
+    /// happens AFTER the burn (where the reclaim goes, how fees are taken), but the record-and-burn step is
+    /// identical.
+    /// @param holder The account whose project tokens are being burned.
+    /// @param projectId The ID of the project the project tokens belong to.
+    /// @param cashOutCount The number of project tokens to burn.
+    /// @param tokenToReclaim The terminal token to reclaim from the project's surplus.
+    /// @param beneficiaryIsFeeless Whether the cash out's beneficiary is a feeless address (passed through
+    /// to the data hook context via the store).
+    /// @param metadata Bytes to send along to the data hook.
+    /// @return ruleset The ruleset the cash out is being made during.
+    /// @return reclaimAmount The amount of terminal tokens to be reclaimed.
+    /// @return cashOutTaxRate The cash out tax rate being used.
+    /// @return hookSpecifications The cash out hook specifications returned by the data hook.
+    function _recordAndBurnCashOut(
+        address holder,
+        uint256 projectId,
+        uint256 cashOutCount,
+        address tokenToReclaim,
+        bool beneficiaryIsFeeless,
+        bytes memory metadata
+    )
+        internal
+        returns (
+            JBRuleset memory ruleset,
+            uint256 reclaimAmount,
+            uint256 cashOutTaxRate,
+            JBCashOutHookSpecification[] memory hookSpecifications
+        )
+    {
+        // Cache the controller to avoid a redundant external call (also used inside STORE.recordCashOutFor).
+        IJBController controller = _controllerOf(projectId);
+
+        // Record the cash out.
+        (ruleset, reclaimAmount, cashOutTaxRate, hookSpecifications) = STORE.recordCashOutFor({
+            holder: holder,
+            projectId: projectId,
+            cashOutCount: cashOutCount,
+            tokenToReclaim: tokenToReclaim,
+            beneficiaryIsFeeless: beneficiaryIsFeeless,
+            metadata: metadata
+        });
+
+        // Burn the project tokens.
+        if (cashOutCount != 0) {
+            controller.burnTokensOf({holder: holder, projectId: projectId, tokenCount: cashOutCount, memo: ""});
+        }
+    }
+
+    /// @notice Resolve B's primary terminal for the reclaim token, reverting if the directory has no entry.
+    /// @dev Shared by `_routeReclaimToBeneficiaryProject` and `_routeReclaimAsAddToBalance`.
+    function _resolveBeneficiaryTerminal(
+        uint256 beneficiaryProjectId,
+        address tokenToReclaim
+    )
+        internal
+        view
+        returns (IJBTerminal destinationTerminal)
+    {
+        destinationTerminal = DIRECTORY.primaryTerminalOf({projectId: beneficiaryProjectId, token: tokenToReclaim});
+        if (address(destinationTerminal) == address(0)) {
+            revert JBMultiTerminal_RecipientProjectTerminalNotFound({
+                projectId: beneficiaryProjectId, token: tokenToReclaim
+            });
+        }
+    }
+
     /// @notice Returns held fees to the project who paid them based on the specified amount.
     /// @dev Partial replenishments use the raw floor calculation so repaying a dust amount cannot both credit the
     /// payer project and leave the fee project owed the 1-unit minimum fee.
@@ -1716,73 +1889,52 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     /// @return returnedFees The amount of held fees that were returned, as a fixed point number with the same number of
     /// decimals as the token's accounting context.
     function _returnHeldFees(uint256 projectId, address token, uint256 amount) internal returns (uint256 returnedFees) {
-        // Keep a reference to the start index.
-        uint256 startIndex = _nextHeldFeeIndexOf[projectId][token];
-
-        // Get a reference to the project's held fees.
-        uint256 numberOfHeldFees = _heldFeesOf[projectId][token].length;
-
-        // If the start index is greater than or equal to the number of held fees, return 0.
-        if (startIndex >= numberOfHeldFees) return 0;
-
-        // Get a reference to the leftover amount once all fees have been settled.
-        uint256 leftoverAmount = amount;
-
-        // Keep a reference to the number of iterations to perform.
-        uint256 count = numberOfHeldFees - startIndex;
-
-        // Keep a reference to the new start index.
-        uint256 newStartIndex = startIndex;
-
-        // Process each fee.
-        for (uint256 i; i < count;) {
-            // Save the fee being iterated on.
-            JBFee memory heldFee = _heldFeesOf[projectId][token][startIndex + i];
-
-            if (leftoverAmount == 0) {
-                break;
-            } else {
-                // Notice here we take `feeAmountFrom` on the stored `.amount`.
-                uint256 feeAmount = _feeAmountFrom(heldFee.amount);
-
-                // Keep a reference to the amount from which the fee was taken.
-                uint256 amountPaidOut = heldFee.amount - feeAmount;
-
-                if (leftoverAmount >= amountPaidOut) {
-                    unchecked {
-                        leftoverAmount -= amountPaidOut;
-                        returnedFees += feeAmount;
-                    }
-
-                    // Move the start index forward to the held fee after the current one.
-                    newStartIndex = startIndex + i + 1;
-                } else {
-                    feeAmount = JBFees.feeAmountResultingIn({amountAfterFee: leftoverAmount, feePercent: FEE});
-
-                    // Get fee from `leftoverAmount`.
-                    unchecked {
-                        _heldFeesOf[projectId][token][startIndex + i].amount -= (leftoverAmount + feeAmount);
-                        returnedFees += feeAmount;
-                    }
-                    leftoverAmount = 0;
-                }
-            }
-            unchecked {
-                ++i;
-            }
-        }
-
-        // Update the next held fee index.
-        if (startIndex != newStartIndex) _nextHeldFeeIndexOf[projectId][token] = newStartIndex;
-
-        emit ReturnHeldFees({
+        returnedFees = JBHeldFeesLib.returnHeldFees({
+            heldFeesOf: _heldFeesOf,
+            nextHeldFeeIndexOf: _nextHeldFeeIndexOf,
             projectId: projectId,
             token: token,
-            amount: amount,
-            returnedFees: returnedFees,
-            leftoverAmount: leftoverAmount,
-            caller: _msgSender()
+            amount: amount
+        });
+    }
+
+    /// @notice Routes the cashout reclaim to B's primary terminal as a `pay` and credits B's fee-free
+    /// surplus by the delivery delta on the first of B's accounting contexts that grew.
+    /// @dev Extracted from the external `payAfterCashOutTokensOf` to keep that function under the
+    /// via-IR-free stack ceiling. Uses `_efficientPay` (handles same-terminal vs cross-terminal with
+    /// `_beforeTransferTo`/`_afterTransferTo`). `minReturnedTokens: 0` is enforced inside `_efficientPay`;
+    /// the user-facing mint floor is `_checkMin(beneficiaryTokenCount, minTokensOut)` in the caller.
+    /// @param tokenToReclaim The token reclaimed from the source project.
+    /// @param reclaimAmount The amount of `tokenToReclaim` being routed.
+    /// @param beneficiaryProjectId The destination project.
+    /// @param beneficiary The address that receives the newly minted destination-project tokens.
+    /// @param payMetadata Bytes forwarded to the destination project's pay flow.
+    /// @return beneficiaryTokenCount The number of destination-project tokens minted to `beneficiary`.
+    function _routeReclaimToBeneficiaryProject(
+        address tokenToReclaim,
+        uint256 reclaimAmount,
+        uint256 beneficiaryProjectId,
+        address beneficiary,
+        bytes memory payMetadata
+    )
+        internal
+        returns (uint256 beneficiaryTokenCount)
+    {
+        IJBTerminal destinationTerminal = _resolveBeneficiaryTerminal(beneficiaryProjectId, tokenToReclaim);
+        (JBAccountingContext[] memory contexts, uint256[] memory balancesBefore) =
+            _snapshotBeneficiaryContextBalances(beneficiaryProjectId);
+
+        beneficiaryTokenCount = _efficientPay({
+            terminal: destinationTerminal,
+            projectId: beneficiaryProjectId,
+            token: tokenToReclaim,
+            amount: reclaimAmount,
+            payer: _msgSender(),
+            beneficiary: beneficiary,
+            metadata: payMetadata
         });
+
+        _creditFirstGrowingBeneficiaryContext(beneficiaryProjectId, contexts, balancesBefore);
     }
 
     /// @notice Sends payouts to a project's payout split group using the specified ruleset.
@@ -1901,7 +2053,31 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         });
     }
 
-    /// @notice Takes a fee into the platform's project (with the `_FEE_BENEFICIARY_PROJECT_ID`).
+    /// @notice Snapshot B's accounting contexts and pre-routing balances on this terminal.
+    /// @dev Shared by `_routeReclaimToBeneficiaryProject` and `_routeReclaimAsAddToBalance`. Reverts if B has
+    /// no accounting contexts on this terminal — without buckets to deliver into, nothing can land here.
+    function _snapshotBeneficiaryContextBalances(uint256 beneficiaryProjectId)
+        internal
+        view
+        returns (JBAccountingContext[] memory contexts, uint256[] memory balancesBefore)
+    {
+        contexts = STORE.accountingContextsOf({terminal: address(this), projectId: beneficiaryProjectId});
+
+        if (contexts.length == 0) {
+            revert JBMultiTerminal_BeneficiaryProjectHasNoAccountingContexts(beneficiaryProjectId);
+        }
+
+        balancesBefore = new uint256[](contexts.length);
+        for (uint256 i; i < contexts.length;) {
+            balancesBefore[i] =
+                STORE.balanceOf({terminal: address(this), projectId: beneficiaryProjectId, token: contexts[i].token});
+            unchecked {
+                ++i;
+            }
+        }
+    }
+
+    /// @notice Takes a fee into the platform's project (with the `JBConstants.FEE_BENEFICIARY_PROJECT_ID`).
     /// @param projectId The ID of the project paying the fee.
     /// @param token The address of the token that the fee is paid in.
     /// @param amount The fee's token amount, as a fixed point number with 18 decimals.
@@ -1942,7 +2118,8 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             });
         } else {
             // Get the terminal that'll receive the fee if one wasn't provided.
-            IJBTerminal feeTerminal = _primaryTerminalOf({projectId: _FEE_BENEFICIARY_PROJECT_ID, token: token});
+            IJBTerminal feeTerminal =
+                _primaryTerminalOf({projectId: JBConstants.FEE_BENEFICIARY_PROJECT_ID, token: token});
 
             // Process the fee.
             _processFee({
@@ -2148,6 +2325,23 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         return DIRECTORY.primaryTerminalOf({projectId: projectId, token: token});
     }
 
+    /// @notice Revert if the destination project's current ruleset has opted out of cross-project fee-free
+    /// inflows (`pauseCrossProjectFeeFreeInflows == true`). Shared by `payAfterCashOutTokensOf` and
+    /// `addToBalanceAfterCashOutTokensOf`.
+    function _requireBeneficiaryAcceptsFeeFreeInflows(uint256 beneficiaryProjectId) internal view {
+        (, JBRulesetMetadata memory bMetadata) =
+            _controllerOf(beneficiaryProjectId).currentRulesetOf(beneficiaryProjectId);
+        if (bMetadata.pauseCrossProjectFeeFreeInflows) {
+            revert JBMultiTerminal_BeneficiaryProjectFeeFreeInflowsPaused(beneficiaryProjectId);
+        }
+    }
+
+    /// @notice Require the caller to have `CASH_OUT_TOKENS` permission for `holder` on `projectId`. Shared by
+    /// `cashOutTokensOf`, `payAfterCashOutTokensOf`, and `addToBalanceAfterCashOutTokensOf`.
+    function _requireCashOutPermissionFrom(address holder, uint256 projectId) internal view {
+        _requirePermissionFrom({account: holder, projectId: projectId, permissionId: JBPermissionIds.CASH_OUT_TOKENS});
+    }
+
     /// @notice Packages a payment amount with the token's accounting context.
     /// @param projectId The ID of the project the token amount belongs to.
     /// @param token The token to pay with.
@@ -2178,6 +2372,6 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     /// @param amount The amount before the fee is applied.
     /// @return The fee amount.
     function _feeAmountFrom(uint256 amount) private pure returns (uint256) {
-        return JBFees.feeAmountFrom({amountBeforeFee: amount, feePercent: FEE});
+        return JBFees.standardFeeAmountFrom(amount);
     }
 }