@bananapus/core-v6 0.0.49 → 0.0.52

package/src/interfaces/IJBCashOutTerminal.sol

@@ -9,6 +9,39 @@ import {JBRuleset} from "../structs/JBRuleset.sol";
 
 /// @notice A terminal that can be cashed out from.
 interface IJBCashOutTerminal is IJBTerminal {
+    /// @notice Atomically cash out a holder's tokens of one project and add the reclaim to another project'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). Held-fee return is hardcoded to `false` on the destination side — this
+    /// entrypoint is for value top-up only, not fee unlock.
+    /// @dev The destination terminal is whichever terminal the directory has registered as the beneficiary
+    /// project's primary terminal for `tokenToReclaim` (which may itself be a router that swaps before adding
+    /// to balance). Cashout-side hooks (if specified by the data hook) execute additively.
+    /// @dev Round-trip fee preservation is enforced by snapshotting the beneficiary project's
+    /// accounting-context balances on this terminal before and after the routing, and crediting
+    /// `_feeFreeSurplusOf` by the per-token delta on each context that grew. The beneficiary project's current
+    /// ruleset can set `pauseCrossProjectFeeFreeInflows` to opt out.
+    /// @param holder The address whose project tokens are being burned.
+    /// @param projectId The ID of the project whose project tokens are being burned.
+    /// @param cashOutCount The number of project tokens to burn.
+    /// @param tokenToReclaim The terminal token reclaimed from the source project's surplus.
+    /// @param beneficiaryProjectId The destination project receiving the reclaim.
+    /// @param cashOutMetadata Forwarded to the source project's data hook and any cashout hook specifications.
+    /// @param addToBalanceMetadata 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
+        returns (uint256 reclaimAmount);
+
     /// @notice A cash out was processed for a project.
     /// @param rulesetId The ID of the ruleset during the cash out.
     /// @param rulesetCycleNumber The cycle number of the ruleset during the cash out.
@@ -96,4 +129,39 @@ interface IJBCashOutTerminal is IJBTerminal {
     )
         external
         returns (uint256 reclaimAmount);
+
+    /// @notice Atomically cash out a holder's tokens of one project and pay the reclaim into another. 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).
+    /// @dev The destination terminal is whichever terminal the directory has registered as the beneficiary project's
+    /// primary terminal for `tokenToReclaim` (which may itself be a router that swaps before paying). Cashout-side
+    /// hooks (if specified by the data hook) execute additively.
+    /// @dev Round-trip fee preservation is enforced by snapshotting the beneficiary project's accounting-context
+    /// balances on this terminal before and after the routing, and crediting `_feeFreeSurplusOf` by the per-token
+    /// delta on each context that grew. The beneficiary project's current ruleset can set
+    /// `pauseCrossProjectFeeFreeInflows` to opt out.
+    /// @param holder The address whose project tokens are being burned.
+    /// @param projectId The ID of the project whose project tokens are being burned.
+    /// @param cashOutCount The number of project tokens to burn.
+    /// @param tokenToReclaim The terminal token reclaimed from the source project's surplus.
+    /// @param beneficiaryProjectId The destination project.
+    /// @param beneficiary The address that receives the newly minted tokens of the destination project.
+    /// @param minTokensOut The minimum number of destination-project tokens that must be minted; reverts otherwise.
+    /// @param cashOutMetadata Forwarded to the source project's data hook and any cashout hook specifications.
+    /// @param payMetadata 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
+        returns (uint256 reclaimAmount, uint256 beneficiaryTokenCount);
 }

package/src/interfaces/IJBFeeTerminal.sol

@@ -71,9 +71,6 @@ interface IJBFeeTerminal is IJBTerminal {
         address caller
     );
 
-    /// @notice The terminal's fee as a fraction of `JBConstants.MAX_FEE`.
-    function FEE() external view returns (uint256);
-
     /// @notice The contract that tracks feeless addresses.
     function FEELESS_ADDRESSES() external view returns (IJBFeelessAddresses);
 

package/src/libraries/JBCashOutHookSpecsLib.sol

@@ -0,0 +1,181 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.28;
+
+import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
+import {SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
+
+import {IJBCashOutHook} from "../interfaces/IJBCashOutHook.sol";
+import {IJBFeelessAddresses} from "../interfaces/IJBFeelessAddresses.sol";
+import {JBAfterCashOutRecordedContext} from "../structs/JBAfterCashOutRecordedContext.sol";
+import {JBCashOutHookSpecification} from "../structs/JBCashOutHookSpecification.sol";
+import {JBRuleset} from "../structs/JBRuleset.sol";
+import {JBTokenAmount} from "../structs/JBTokenAmount.sol";
+import {JBConstants} from "./JBConstants.sol";
+import {JBFees} from "./JBFees.sol";
+
+/// @notice Cash-out hook specification fulfillment for `JBMultiTerminal`. Extracted to reduce terminal
+/// bytecode size, mirroring the `JBHeldFeesLib` pattern.
+/// @dev Called via DELEGATECALL — `address(this)` inside library code is the terminal's address, so token
+/// approvals and ETH-bearing hook calls operate on the terminal's balance and allowances. Events are
+/// emitted from the terminal address. The `caller` field of `HookAfterRecordCashOut` uses raw `msg.sender`
+/// (matching `JBHeldFeesLib`'s precedent) — this means meta-transactions through a trusted forwarder will
+/// surface the forwarder address in the event slot, but the actual hook execution semantics are unaffected.
+library JBCashOutHookSpecsLib {
+    // A library that adds default safety checks to ERC20 functionality.
+    using SafeERC20 for IERC20;
+
+    //*********************************************************************//
+    // ------------------------------ events ----------------------------- //
+    //*********************************************************************//
+
+    /// @notice A cash out hook was called after a cash out was recorded.
+    /// @param hook The cash out hook that was called.
+    /// @param context The context passed to the hook.
+    /// @param specificationAmount The amount specified for the hook.
+    /// @param fee The fee taken from the hook's amount.
+    /// @param caller The address that called the cash out function.
+    event HookAfterRecordCashOut(
+        IJBCashOutHook indexed hook,
+        JBAfterCashOutRecordedContext context,
+        uint256 specificationAmount,
+        uint256 fee,
+        address caller
+    );
+
+    //*********************************************************************//
+    // --------------------------- custom errors ------------------------- //
+    //*********************************************************************//
+
+    /// @notice Thrown when a hook returns without consuming the full forwarded ERC-20 amount.
+    error JBMultiTerminal_TemporaryAllowanceNotConsumed(address token, address spender, uint256 allowance);
+
+    //*********************************************************************//
+    // ----------------------- external functions ------------------------ //
+    //*********************************************************************//
+
+    /// @notice Iterates `specifications`, calling each non-noop hook with the right ETH/ERC-20 setup, and
+    /// accumulates the fee-eligible amount across non-feeless hooks.
+    /// @dev For each spec: if the hook is feeless, it gets the full spec amount; otherwise the hook gets
+    /// `amount - feeAmountFrom(amount)` and the gross spec amount is added to the eligible-for-fees total
+    /// (the caller takes the fee separately via `_takeFeeFrom`). Cross-token semantics: the hook context's
+    /// `forwardedAmount` carries the post-fee amount in the same token as `beneficiaryReclaimAmount`.
+    /// @param feelessAddresses Registry of fee-exempt addresses (consulted per-hook).
+    /// @param projectId The project being cashed out from.
+    /// @param beneficiaryReclaimAmount The token amount reference (token, decimals, currency, gross value).
+    /// @param holder The account whose project tokens were burned.
+    /// @param cashOutCount The number of project tokens burned.
+    /// @param metadata Bytes forwarded to each hook as `cashOutMetadata`.
+    /// @param ruleset The ruleset active during the cash out.
+    /// @param cashOutTaxRate The cash out tax rate applied.
+    /// @param beneficiary The address forwarded as the hook context's `beneficiary` (typically the user-supplied
+    /// recipient or `address(this)` for cross-project flows where the terminal custodies the reclaim mid-flow).
+    /// @param specifications The hook specifications returned by the data hook.
+    /// @return amountEligibleForFees Total spec amounts (gross) from non-feeless hooks, used by the caller to
+    /// charge fees in a single pass.
+    function fulfill(
+        IJBFeelessAddresses feelessAddresses,
+        uint256 projectId,
+        JBTokenAmount memory beneficiaryReclaimAmount,
+        address holder,
+        uint256 cashOutCount,
+        bytes memory metadata,
+        JBRuleset memory ruleset,
+        uint256 cashOutTaxRate,
+        address payable beneficiary,
+        JBCashOutHookSpecification[] memory specifications
+    )
+        external
+        returns (uint256 amountEligibleForFees)
+    {
+        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;) {
+            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 = feelessAddresses.isFeelessFor({
+                addr: address(specification.hook), projectId: projectId
+            })
+                ? 0
+                : JBFees.standardFeeAmountFrom({amountBeforeFee: 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: msg.sender
+            });
+            unchecked {
+                ++i;
+            }
+        }
+    }
+
+    //*********************************************************************//
+    // ----------------------- private helpers --------------------------- //
+    //*********************************************************************//
+
+    /// @notice Native-token transfers use `msg.value` (return the amount). ERC20 transfers grant a temporary
+    /// pull allowance and return 0 (the recipient is expected to consume it within the same call).
+    function _beforeTransferTo(address to, address token, uint256 amount) private returns (uint256) {
+        if (token == JBConstants.NATIVE_TOKEN) return amount;
+        IERC20(token).forceApprove({spender: to, value: amount});
+        return 0;
+    }
+
+    /// @notice Asserts the recipient consumed the temporary ERC20 allowance. No-op for native token.
+    function _afterTransferTo(address to, address token) private view {
+        if (token == JBConstants.NATIVE_TOKEN) return;
+        uint256 allowance = IERC20(token).allowance({owner: address(this), spender: to});
+        if (allowance != 0) revert JBMultiTerminal_TemporaryAllowanceNotConsumed(token, to, allowance);
+    }
+}

package/src/libraries/JBConstants.sol

@@ -20,4 +20,10 @@ library JBConstants {
 
     /// @notice The fee denominator. The protocol fee is `FEE / MAX_FEE` (currently 25/1000 = 2.5%).
     uint16 public constant MAX_FEE = 1000;
+
+    /// @notice The fee numerator. The protocol fee is `FEE / MAX_FEE` = 25/1000 = 2.5%, charged on outflows.
+    uint16 public constant FEE = 25;
+
+    /// @notice The project ID that receives protocol fees. Should be the first project launched at deployment.
+    uint256 public constant FEE_BENEFICIARY_PROJECT_ID = 1;
 }

package/src/libraries/JBFees.sol

@@ -27,4 +27,29 @@ library JBFees {
     function feeAmountFrom(uint256 amountBeforeFee, uint256 feePercent) internal pure returns (uint256) {
         return mulDiv(amountBeforeFee, feePercent, JBConstants.MAX_FEE);
     }
+
+    /// @notice Specialization of `feeAmountFrom` that hardcodes the standard protocol fee
+    /// (`JBConstants.FEE / JBConstants.MAX_FEE` = 25 / 1000 = 1 / 40). Both numerator and denominator are
+    /// compile-time constants so callers don't need to pass them every call.
+    /// @dev Pre-reduced: `mulDiv(amount, 25, 1000)` ≡ `amount / 40` (gcd(25, 1000) = 25). Plain integer
+    /// division is exact (rounds down) and shaves the entire `mulDiv` 512-bit pipeline at every fee site.
+    /// If `JBConstants.FEE` or `JBConstants.MAX_FEE` changes, the constant `40` here MUST be reduced again.
+    /// @param amountBeforeFee The amount before the fee is applied, as a fixed point number.
+    /// @return The fee amount, as a fixed point number with the same number of decimals as `amountBeforeFee`.
+    function standardFeeAmountFrom(uint256 amountBeforeFee) internal pure returns (uint256) {
+        return amountBeforeFee / 40;
+    }
+
+    /// @notice Specialization of `feeAmountResultingIn` that hardcodes the standard protocol fee
+    /// (`JBConstants.FEE / JBConstants.MAX_FEE`). Use to back-calculate the standard fee from a known
+    /// post-fee payout.
+    /// @dev Pre-reduced: `mulDiv(amount, 1000, 1000 - 25) - amount` ≡ `mulDiv(amount, 40, 39) - amount`
+    /// (gcd(1000, 975) = 25). `mulDiv` (not raw `*`) preserves overflow-safety for the rare wildly-large
+    /// inputs and matches the rounding behavior of `feeAmountResultingIn` exactly. If `JBConstants.FEE` or
+    /// `JBConstants.MAX_FEE` changes, the constants `40` and `39` here MUST be reduced again.
+    /// @param amountAfterFee The desired post-fee amount, as a fixed point number.
+    /// @return The fee amount that, when added to `amountAfterFee`, yields the gross pre-fee amount.
+    function standardFeeAmountResultingIn(uint256 amountAfterFee) internal pure returns (uint256) {
+        return mulDiv(amountAfterFee, 40, 39) - amountAfterFee;
+    }
 }

package/src/libraries/JBHeldFeesLib.sol

@@ -0,0 +1,288 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.28;
+
+import {IJBDirectory} from "../interfaces/IJBDirectory.sol";
+import {IJBTerminal} from "../interfaces/IJBTerminal.sol";
+import {IJBTerminalStore} from "../interfaces/IJBTerminalStore.sol";
+import {JBFee} from "../structs/JBFee.sol";
+import {JBConstants} from "./JBConstants.sol";
+import {JBFees} from "./JBFees.sol";
+
+/// @notice Local callback into the terminal's `executeProcessFee(...)`. Kept here because the function is an
+/// implementation detail of the library/terminal pair, not a shared public interface.
+interface IJBHeldFeesExecutor {
+    /// @notice Sends a fee amount from a project to the fee-receiving terminal under an external CALL boundary,
+    /// so the library can wrap the call in `try/catch` (revert in the fee route is forgiven, not propagated).
+    /// @param projectId The project paying the fee.
+    /// @param token The token the fee is denominated in.
+    /// @param amount The fee amount.
+    /// @param beneficiary The address that receives any platform tokens minted by the fee payment.
+    /// @param feeTerminal The terminal that'll receive the fee.
+    function executeProcessFee(
+        uint256 projectId,
+        address token,
+        uint256 amount,
+        address beneficiary,
+        IJBTerminal feeTerminal
+    )
+        external;
+}
+
+/// @notice Held-fee bookkeeping for `JBMultiTerminal`. Extracted to reduce terminal bytecode size.
+/// @dev Called via DELEGATECALL — storage refs (`heldFeesOf`, `nextHeldFeeIndexOf`) point at the terminal's
+/// storage. `address(this)` inside library code is the terminal's address. Events are therefore emitted from
+/// the terminal.
+library JBHeldFeesLib {
+    //*********************************************************************//
+    // ------------------------------ events ----------------------------- //
+    //*********************************************************************//
+
+    /// @notice Emitted when a fee is sent to the fee-receiving terminal.
+    /// @param projectId The project the fee was for.
+    /// @param token The token the fee was paid in.
+    /// @param amount The fee amount.
+    /// @param wasHeld Whether the fee was previously held (true) or processed inline (false).
+    /// @param beneficiary The address that received any platform tokens minted by the fee payment.
+    /// @param caller The address that triggered the fee processing.
+    event ProcessFee(
+        uint256 indexed projectId,
+        address indexed token,
+        uint256 amount,
+        bool wasHeld,
+        address beneficiary,
+        address caller
+    );
+
+    /// @notice Emitted when a fee payment reverts and the amount is returned to the project's balance.
+    /// @param projectId The project the fee was for.
+    /// @param token The token the fee was paid in.
+    /// @param feeProjectId The ID of the fee-receiving project.
+    /// @param amount The fee amount returned.
+    /// @param reason The revert reason from the fee route.
+    /// @param caller The address that triggered the fee processing.
+    event FeeReverted(
+        uint256 indexed projectId,
+        address indexed token,
+        uint256 indexed feeProjectId,
+        uint256 amount,
+        bytes reason,
+        address caller
+    );
+
+    /// @notice Emitted when held fees are returned to the project's balance (e.g. on an `addToBalanceOf`).
+    /// @param projectId The project whose held fees were returned.
+    /// @param token The token the held fees were denominated in.
+    /// @param amount The amount used as the basis for the return calculation.
+    /// @param returnedFees The amount of fees actually returned.
+    /// @param leftoverAmount Any leftover from the basis amount that did not match a held fee.
+    /// @param caller The address that triggered the return.
+    event ReturnHeldFees(
+        uint256 indexed projectId,
+        address indexed token,
+        uint256 amount,
+        uint256 returnedFees,
+        uint256 leftoverAmount,
+        address caller
+    );
+
+    //*********************************************************************//
+    // ----------------------- internal functions ------------------------ //
+    //*********************************************************************//
+
+    /// @notice Processes up to `count` unlocked held fees for `(projectId, token)`, forwarding each to the fee
+    /// terminal and reclaiming the storage slot once the queue is drained.
+    /// @dev Re-reads `nextHeldFeeIndexOf[projectId][token]` from storage each iteration to be reentrancy-safe
+    /// against any nested call that may have advanced the index. The entry is deleted and the index advanced
+    /// BEFORE the external call so a reverting fee route cannot be replayed.
+    /// @param heldFeesOf Storage ref to the terminal's per-(project,token) held-fee queue.
+    /// @param nextHeldFeeIndexOf Storage ref to the next-index cursor for each (project,token) queue.
+    /// @param directory The terminal's directory, used to locate the fee-receiving terminal.
+    /// @param store The terminal's store, used to credit the fee back to the project on a failed route.
+    /// @param projectId The project to process held fees for.
+    /// @param token The token the held fees are denominated in.
+    /// @param count The maximum number of held fees to process.
+    function processHeldFees(
+        mapping(uint256 => mapping(address => JBFee[])) storage heldFeesOf,
+        mapping(uint256 => mapping(address => uint256)) storage nextHeldFeeIndexOf,
+        IJBDirectory directory,
+        IJBTerminalStore store,
+        uint256 projectId,
+        address token,
+        uint256 count
+    )
+        external
+    {
+        // Resolve the fee-receiving terminal once outside the loop.
+        IJBTerminal feeTerminal =
+            directory.primaryTerminalOf({projectId: JBConstants.FEE_BENEFICIARY_PROJECT_ID, token: token});
+
+        for (uint256 i; i < count;) {
+            uint256 currentIndex = nextHeldFeeIndexOf[projectId][token];
+
+            // Queue exhausted — break early so we can run the array cleanup below.
+            if (currentIndex >= heldFeesOf[projectId][token].length) break;
+
+            JBFee memory heldFee = heldFeesOf[projectId][token][currentIndex];
+
+            // Fees unlock sequentially; if the head isn't ready, nothing later is either.
+            // forge-lint: disable-next-line(block-timestamp)
+            if (heldFee.unlockTimestamp > block.timestamp) break;
+
+            // Delete + advance index BEFORE the external call (reentrancy safety: a reentrant
+            // `processHeldFeesOf` cannot re-process the same entry).
+            delete heldFeesOf[projectId][token][currentIndex];
+            nextHeldFeeIndexOf[projectId][token] = currentIndex + 1;
+
+            processFee({
+                store: store,
+                projectId: projectId,
+                token: token,
+                amount: JBFees.standardFeeAmountFrom({amountBeforeFee: heldFee.amount}),
+                beneficiary: heldFee.beneficiary,
+                feeTerminal: feeTerminal,
+                wasHeld: true
+            });
+
+            unchecked {
+                ++i;
+            }
+        }
+
+        // Reclaim the array storage slot once the queue has been fully drained.
+        if (
+            nextHeldFeeIndexOf[projectId][token] >= heldFeesOf[projectId][token].length
+                && heldFeesOf[projectId][token].length > 0
+        ) {
+            delete heldFeesOf[projectId][token];
+            delete nextHeldFeeIndexOf[projectId][token];
+        }
+    }
+
+    /// @notice Sends a fee to the fee-receiving terminal under a try/catch boundary.
+    /// @dev Routed through `IJBHeldFeesExecutor(address(this)).executeProcessFee(...)` so the call is a real
+    /// external CALL (try/catch semantics require it). Under DELEGATECALL `address(this)` is the terminal, so
+    /// this becomes a call to the terminal's `executeProcessFee` whose `msg.sender == address(this)` check
+    /// passes. On revert the amount is forgiven and added back to the project's balance — by design, a broken
+    /// fee route should not permanently lock project funds.
+    /// @param store The terminal's store, used for the forgive-on-revert credit.
+    /// @param projectId The project paying the fee.
+    /// @param token The token the fee is denominated in.
+    /// @param amount The fee amount.
+    /// @param beneficiary The address that receives any platform tokens minted by the fee payment.
+    /// @param feeTerminal The terminal that'll receive the fee.
+    /// @param wasHeld Whether the fee was previously held (true) or processed inline (false).
+    function processFee(
+        IJBTerminalStore store,
+        uint256 projectId,
+        address token,
+        uint256 amount,
+        address beneficiary,
+        IJBTerminal feeTerminal,
+        bool wasHeld
+    )
+        public
+    {
+        try IJBHeldFeesExecutor(address(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: msg.sender
+            });
+        } catch (bytes memory reason) {
+            // Forgive the fee, credit it back to the project, and surface the failure for off-chain observability.
+            emit FeeReverted({
+                projectId: projectId,
+                token: token,
+                feeProjectId: JBConstants.FEE_BENEFICIARY_PROJECT_ID,
+                amount: amount,
+                reason: reason,
+                caller: msg.sender
+            });
+
+            store.recordAddedBalanceFor({projectId: projectId, token: token, amount: amount});
+        }
+    }
+
+    /// @notice Returns held fees up to `amount` in FIFO order from the project's held-fee queue.
+    /// @dev Walks the queue from `nextHeldFeeIndexOf` forward. Whole entries are consumed when `leftoverAmount`
+    /// covers their post-fee amount; the final entry can be partially consumed by shrinking its `.amount` in
+    /// place. The fee implied by the partial-consume branch uses `feeAmountResultingIn` (inverse of
+    /// `feeAmountFrom`) so the credited fee aligns with the amount that was actually returned. Dust amounts
+    /// below the floor produce `feeAmount == 0`.
+    /// @param heldFeesOf Storage ref to the terminal's per-(project,token) held-fee queue.
+    /// @param nextHeldFeeIndexOf Storage ref to the next-index cursor for each (project,token) queue.
+    /// @param projectId The project to return held fees for.
+    /// @param token The token the held fees are denominated in.
+    /// @param amount The reference amount to base the return on (typically the inbound addToBalance amount).
+    /// @return returnedFees The total fee amount returned to the project.
+    function returnHeldFees(
+        mapping(uint256 => mapping(address => JBFee[])) storage heldFeesOf,
+        mapping(uint256 => mapping(address => uint256)) storage nextHeldFeeIndexOf,
+        uint256 projectId,
+        address token,
+        uint256 amount
+    )
+        external
+        returns (uint256 returnedFees)
+    {
+        uint256 startIndex = nextHeldFeeIndexOf[projectId][token];
+        uint256 numberOfHeldFees = heldFeesOf[projectId][token].length;
+
+        // Empty queue — nothing to return.
+        if (startIndex >= numberOfHeldFees) return 0;
+
+        uint256 leftoverAmount = amount;
+        uint256 count = numberOfHeldFees - startIndex;
+        uint256 newStartIndex = startIndex;
+
+        for (uint256 i; i < count;) {
+            JBFee memory heldFee = heldFeesOf[projectId][token][startIndex + i];
+
+            if (leftoverAmount == 0) {
+                break;
+            } else {
+                // Recompute the fee charged on the stored gross amount so partial returns stay aligned.
+                uint256 feeAmount = JBFees.standardFeeAmountFrom({amountBeforeFee: heldFee.amount});
+                uint256 amountPaidOut = heldFee.amount - feeAmount;
+
+                if (leftoverAmount >= amountPaidOut) {
+                    // Whole entry consumed: credit its full fee, advance the cursor past it.
+                    unchecked {
+                        leftoverAmount -= amountPaidOut;
+                        returnedFees += feeAmount;
+                    }
+                    newStartIndex = startIndex + i + 1;
+                } else {
+                    // Partial entry: shrink the stored entry by what we consumed (incl. its own fee).
+                    feeAmount = JBFees.standardFeeAmountResultingIn({amountAfterFee: leftoverAmount});
+                    unchecked {
+                        heldFeesOf[projectId][token][startIndex + i].amount -= (leftoverAmount + feeAmount);
+                        returnedFees += feeAmount;
+                    }
+                    leftoverAmount = 0;
+                }
+            }
+
+            unchecked {
+                ++i;
+            }
+        }
+
+        if (startIndex != newStartIndex) nextHeldFeeIndexOf[projectId][token] = newStartIndex;
+
+        emit ReturnHeldFees({
+            projectId: projectId,
+            token: token,
+            amount: amount,
+            returnedFees: returnedFees,
+            leftoverAmount: leftoverAmount,
+            caller: msg.sender
+        });
+    }
+}