@bananapus/core-v6 0.0.58 → 0.0.59

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/core-v6",
-  "version": "0.0.58",
+  "version": "0.0.59",
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/JBMultiTerminal.sol

@@ -30,6 +30,7 @@ import {IJBTerminalStore} from "./interfaces/IJBTerminalStore.sol";
 import {IJBTokens} from "./interfaces/IJBTokens.sol";
 import {JBConstants} from "./libraries/JBConstants.sol";
 import {JBFees} from "./libraries/JBFees.sol";
+import {JBHeldFees} from "./libraries/JBHeldFees.sol";
 import {JBMetadataResolver} from "./libraries/JBMetadataResolver.sol";
 import {JBPayoutSplitGroupLib} from "./libraries/JBPayoutSplitGroupLib.sol";
 import {JBRulesetMetadataResolver} from "./libraries/JBRulesetMetadataResolver.sol";
@@ -81,9 +82,6 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     // ------------------------ 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
 
@@ -143,7 +141,26 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     mapping(uint256 projectId => mapping(address token => uint256)) internal _nextHeldFeeIndexOf;
 
     //*********************************************************************//
-    // ------------------- transient stored properties ------------------- //
+    // --------------- public transient stored properties --------------- //
+    //*********************************************************************//
+
+    /// @notice Caller-originated referrer reference for the duration of the current external fee-paying call.
+    /// @dev Encoded as `(referralChainId << 48) | referralProjectId`: bits [79:48] are the referrer's EIP-155 chain
+    /// ID (uint32), bits [47:0] are the referrer's project ID on that chain (uint48). The upper bits of the
+    /// uint256 are reserved for future encoding extensions.
+    /// @dev The entry points `cashOutTokensOf`, `sendPayoutsOf`, and `useAllowanceOf` auto-resolve a bare project ID
+    /// (non-zero project, zero chain bits) to the current execution chain via `block.chainid` before writing this
+    /// slot. So storage (and indexers reading `feeVolumeByReferralOf`) always observe a fully-resolved
+    /// `(chainId, projectId)` pair — callers can write `referralProjectId: someProjectId` without manually packing
+    /// their own chain ID.
+    /// @dev Set by the three entry points via the `_setReferralProjectId` save-restore wrapper. Read inside `_pay`
+    /// to credit `feeVolumeByReferralOf` when the fee project's pay call is recorded locally.
+    /// @dev Public so pay/cashout/split hooks can introspect which referral originated the in-flight call (e.g. to
+    /// apply referral-specific logic). Reads `0` outside any fee-paying call.
+    uint256 public transient override currentReferralProjectId;
+
+    //*********************************************************************//
+    // -------------- internal transient stored properties -------------- //
     //*********************************************************************//
 
     /// @notice Whether this terminal is currently measuring an incoming ERC-20 balance delta.
@@ -277,6 +294,10 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     /// data hook and cash out hook if applicable.
     /// @param metadata Bytes to send along to the emitted event, as well as the data hook and cash out hook if
     /// applicable.
+    /// @param referralProjectId Optional referrer reference to credit with the protocol fee volume taken by this
+    /// call, encoded as `(referralChainId << 48) | referralProjectId` (chain ID in the upper 32 bits, project ID
+    /// in the lower 48). A bare project ID (chain bits zero) is auto-resolved to the current chain via `block.chainid`.
+    /// Pass `0` for no referral credit.
     /// @return reclaimAmount The amount of **terminal tokens** sent to `beneficiary` in exchange for the burned project
     /// tokens, as a fixed point number with the same number of decimals as the terminal token's accounting context.
     function cashOutTokensOf(
@@ -286,7 +307,8 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         address tokenToReclaim,
         uint256 minTokensReclaimed,
         address payable beneficiary,
-        bytes calldata metadata
+        bytes calldata metadata,
+        uint256 referralProjectId
     )
         external
         override
@@ -295,6 +317,9 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         // Enforce permissions.
         _requirePermissionFrom({account: holder, projectId: projectId, permissionId: JBPermissionIds.CASH_OUT_TOKENS});
 
+        // Save-restore the transient referral slot so nested reentrant fee-paying calls don't pollute each other.
+        uint256 priorReferral = _setReferralProjectId(referralProjectId);
+
         reclaimAmount = _cashOutTokensOf({
             holder: holder,
             projectId: projectId,
@@ -304,6 +329,8 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             metadata: metadata
         });
 
+        _setReferralProjectId(priorReferral);
+
         // The amount being reclaimed must be at least as much as was expected.
         _checkMin({value: reclaimAmount, min: minTokensReclaimed});
     }
@@ -498,7 +525,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
 
         _efficientPay({
             terminal: feeTerminal,
-            projectId: _FEE_BENEFICIARY_PROJECT_ID,
+            projectId: JBConstants.FEE_BENEFICIARY_PROJECT_ID,
             token: token,
             amount: amount,
             beneficiary: beneficiary,
@@ -569,7 +596,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
+            ) {
                 // Fee processing failures never block migration. If the fee route is broken, `_processFee` credits
                 // the fee amount back to this source terminal and emits `FeeReverted`; the post-fee amount still
                 // migrates so project funds are not trapped behind project #1 routing issues.
@@ -666,7 +696,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     /// @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});
+        IJBTerminal feeTerminal = _primaryTerminalOf({projectId: JBConstants.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.
@@ -696,6 +726,13 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             delete _heldFeesOf[projectId][token][currentIndex];
             _nextHeldFeeIndexOf[projectId][token] = currentIndex + 1;
 
+            // Restore the originating fee-paying call's referral project for the duration of this fee's processing
+            // so the credit in `_processFee` attributes to the right (chain, project) pair. No save needed:
+            // `processHeldFeesOf` is a top-level keeper call in practice — the incoming transient is 0. Defensive
+            // cleanup happens once after the loop instead of per-iteration. Reconstructs the packed encoding from
+            // the two struct halves: `(chainId << 48) | projectId`.
+            currentReferralProjectId = (uint256(heldFee.referralChainId) << 48) | uint256(heldFee.referralProjectId);
+
             // Process the standard fee on the original gross amount recorded when the held fee was created.
             _processFee({
                 projectId: projectId,
@@ -705,11 +742,17 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
                 feeTerminal: feeTerminal,
                 wasHeld: true
             });
+
             unchecked {
                 ++i;
             }
         }
 
+        // Defensive cleanup: zero the transient so any subsequent in-tx work (e.g. hook reentrancy) doesn't
+        // inherit the last processed fee's referral. EIP-1153 would clear it at end-of-tx anyway, but in-tx
+        // reentry is the only case where this matters.
+        currentReferralProjectId = 0;
+
         // 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
@@ -736,20 +779,29 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     /// in terms of the token's accounting context currency), as a fixed point number with the same number of decimals
     /// as the token's accounting context. If the amount of tokens paid out would be less than this amount, the send is
     /// reverted.
+    /// @param referralProjectId Optional referrer reference to credit with the protocol fee volume taken by this
+    /// call, encoded as `(referralChainId << 48) | referralProjectId` (chain ID in the upper 32 bits, project ID
+    /// in the lower 48). A bare project ID (chain bits zero) is auto-resolved to the current chain via `block.chainid`.
+    /// Pass `0` for no referral credit.
     /// @return amountPaidOut The total amount paid out.
     function sendPayoutsOf(
         uint256 projectId,
         address token,
         uint256 amount,
         uint256 currency,
-        uint256 minTokensPaidOut
+        uint256 minTokensPaidOut,
+        uint256 referralProjectId
     )
         external
         override
         returns (uint256 amountPaidOut)
     {
+        uint256 priorReferral = _setReferralProjectId(referralProjectId);
+
         amountPaidOut = _sendPayoutsOf({projectId: projectId, token: token, amount: amount, currency: currency});
 
+        _setReferralProjectId(priorReferral);
+
         // The amount being paid out must be at least as much as was expected.
         _checkMin({value: amountPaidOut, min: minTokensPaidOut});
     }
@@ -772,6 +824,10 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     /// @param feeBeneficiary The address that receives the **project tokens** minted by the fee project in exchange
     /// for the protocol fee paid in terminal tokens.
     /// @param memo A memo to pass along to the emitted event.
+    /// @param referralProjectId Optional referrer reference to credit with the protocol fee volume taken by this
+    /// call, encoded as `(referralChainId << 48) | referralProjectId` (chain ID in the upper 32 bits, project ID
+    /// in the lower 48). A bare project ID (chain bits zero) is auto-resolved to the current chain via `block.chainid`.
+    /// Pass `0` for no referral credit.
     /// @return netAmountPaidOut The number of **terminal tokens** sent to `beneficiary`, net of the protocol fee, as a
     /// fixed point number with the same number of decimals as the terminal token's accounting context.
     function useAllowanceOf(
@@ -782,7 +838,8 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         uint256 minTokensPaidOut,
         address payable beneficiary,
         address payable feeBeneficiary,
-        string calldata memo
+        string calldata memo,
+        uint256 referralProjectId
     )
         external
         override
@@ -794,6 +851,8 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         // Enforce permissions.
         _requirePermissionFrom({account: owner, projectId: projectId, permissionId: JBPermissionIds.USE_ALLOWANCE});
 
+        uint256 priorReferral = _setReferralProjectId(referralProjectId);
+
         netAmountPaidOut = _useAllowanceOf({
             projectId: projectId,
             owner: owner,
@@ -805,6 +864,8 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             memo: memo
         });
 
+        _setReferralProjectId(priorReferral);
+
         // The amount being withdrawn must be at least as much as was expected.
         _checkMin({value: netAmountPaidOut, min: minTokensPaidOut});
     }
@@ -879,30 +940,15 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         external
         view
         override
-        returns (JBFee[] memory heldFees)
+        returns (JBFee[] memory)
     {
-        // Keep a reference to the start index.
-        uint256 startIndex = _nextHeldFeeIndexOf[projectId][token];
-
-        // Get a reference to the number of 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 new JBFee[](0);
-
-        // If the start index plus the count is greater than the number of fees, set the count to the number of fees
-        if (startIndex + count > numberOfHeldFees) count = numberOfHeldFees - startIndex;
-
-        // Create a new array to hold the fees.
-        heldFees = new JBFee[](count);
-
-        // Copy the fees into the array.
-        for (uint256 i; i < count;) {
-            heldFees[i] = _heldFeesOf[projectId][token][startIndex + i];
-            unchecked {
-                ++i;
-            }
-        }
+        return JBHeldFees.viewHeldFees({
+            heldFeesOf: _heldFeesOf,
+            nextHeldFeeIndexOf: _nextHeldFeeIndexOf,
+            projectId: projectId,
+            token: token,
+            count: count
+        });
     }
 
     /// @notice Simulates a cash out without modifying state — use this to preview how many tokens a holder would
@@ -1705,6 +1751,15 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             payer: payer, amount: tokenAmount, projectId: projectId, beneficiary: beneficiary, metadata: metadata
         });
 
+        // Credit the originating fee-paying call's referral project. This is only meaningful when this pay is a
+        // protocol-fee payment landing on the fee project AND a referral was set by the outer entry point (or
+        // restored from a held fee by `processHeldFeesOf`). The store handles the no-op case when either input is
+        // zero. Done here (after `recordPaymentFrom`) instead of inside the store so the credit logic stays in the
+        // terminal and the store is never asked to call back into us.
+        if (projectId == JBConstants.FEE_BENEFICIARY_PROJECT_ID && currentReferralProjectId != 0) {
+            STORE.recordFeeReferralCreditOf({referralProjectId: currentReferralProjectId, amount: tokenAmount});
+        }
+
         // Only the value retained in the destination balance needs later cashout fee recovery. Non-feeless pay-hook
         // forwards pay their source-equivalent fee inline before leaving the project.
         if (internalSplitPayProjectId != 0) {
@@ -1804,7 +1859,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             emit FeeReverted({
                 projectId: projectId,
                 token: token,
-                feeProjectId: _FEE_BENEFICIARY_PROJECT_ID,
+                feeProjectId: JBConstants.FEE_BENEFICIARY_PROJECT_ID,
                 amount: amount,
                 reason: reason,
                 caller: _msgSender()
@@ -1832,66 +1887,13 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     /// as the token's accounting context.
     /// @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) {
-        // Start from the first held fee that has not already been returned, processed, or forgiven.
-        uint256 startIndex = _nextHeldFeeIndexOf[projectId][token];
-
-        // Use the original array length as the upper bound. Returning held fees never appends new entries.
-        uint256 numberOfHeldFees = _heldFeesOf[projectId][token].length;
-
-        if (startIndex >= numberOfHeldFees) return 0;
-
-        // Track how much of the new balance remains available to match against held fees.
-        uint256 leftoverAmount = amount;
-
-        // Move this forward for each fully returned held fee.
-        uint256 newStartIndex = startIndex;
-
-        for (uint256 i = startIndex; i < numberOfHeldFees;) {
-            if (leftoverAmount == 0) break;
-
-            // Held fees store the original gross amount that paid out before its fee was removed.
-            JBFee memory heldFee = _heldFeesOf[projectId][token][i];
-
-            // Recompute the standard fee associated with the held gross amount.
-            uint256 feeAmount = _feeAmountFrom(heldFee.amount);
-
-            // This is the net amount that originally left the project after the held fee was removed.
-            uint256 amountPaidOut = heldFee.amount - feeAmount;
-
-            if (leftoverAmount >= amountPaidOut) {
-                unchecked {
-                    leftoverAmount -= amountPaidOut;
-                    returnedFees += feeAmount;
-                }
-
-                // Move the start index forward to the fee after this fully returned one.
-                newStartIndex = i + 1;
-            } else {
-                // Only part of this held fee can be returned. Convert the remaining net replenishment back into
-                // its corresponding gross fee and shrink the stored gross amount.
-                feeAmount = JBFees.standardFeeAmountResultingIn(leftoverAmount);
-
-                unchecked {
-                    _heldFeesOf[projectId][token][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({
+    function _returnHeldFees(uint256 projectId, address token, uint256 amount) internal returns (uint256) {
+        return JBHeldFees.returnHeldFees({
+            heldFeesOf: _heldFeesOf,
+            nextHeldFeeIndexOf: _nextHeldFeeIndexOf,
             projectId: projectId,
             token: token,
             amount: amount,
-            returnedFees: returnedFees,
-            leftoverAmount: leftoverAmount,
             caller: _msgSender()
         });
     }
@@ -2012,7 +2014,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         });
     }
 
-    /// @notice Takes a fee into the platform's project (with the `_FEE_BENEFICIARY_PROJECT_ID`).
+    /// @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 the same number of decimals as the token's
@@ -2036,12 +2038,22 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
 
         if (shouldHoldFees) {
             // Store the gross amount so future repayments can recover the corresponding fee.
+            // Capture the in-flight `currentReferralProjectId` so attribution survives the 28-day hold window —
+            // by the time `processHeldFeesOf` runs, the transient slot has been cleared. The encoded
+            // `(chainId << 48) | projectId` pair in the transient slot is decomposed into its two halves so the
+            // struct stays in 2 storage slots.
+            uint256 encodedReferral = currentReferralProjectId;
             _heldFeesOf[projectId][token].push(
                 JBFee({
-                    amount: amount,
+                    // forge-lint: disable-next-line(unsafe-typecast)
+                    amount: uint224(amount),
+                    // forge-lint: disable-next-line(unsafe-typecast)
+                    referralChainId: uint32(encodedReferral >> 48),
                     beneficiary: beneficiary,
                     // forge-lint: disable-next-line(unsafe-typecast)
-                    unlockTimestamp: uint48(block.timestamp + _FEE_HOLDING_SECONDS)
+                    unlockTimestamp: uint48(block.timestamp + _FEE_HOLDING_SECONDS),
+                    // forge-lint: disable-next-line(unsafe-typecast)
+                    referralProjectId: uint48(encodedReferral)
                 })
             );
 
@@ -2055,7 +2067,8 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             });
         } else {
             // Resolve the fee project's terminal for this token and process the fee immediately.
-            IJBTerminal feeTerminal = _primaryTerminalOf({projectId: _FEE_BENEFICIARY_PROJECT_ID, token: token});
+            IJBTerminal feeTerminal =
+                _primaryTerminalOf({projectId: JBConstants.FEE_BENEFICIARY_PROJECT_ID, token: token});
 
             _processFee({
                 projectId: projectId,
@@ -2295,4 +2308,22 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     function _feeAmountFrom(uint256 amount) private pure returns (uint256) {
         return JBFees.standardFeeAmountFrom(amount);
     }
+
+    /// @notice Set the transient `currentReferralProjectId` slot and return the prior value (for save-restore).
+    /// @dev Returning the prior value lets the caller restore it after the inner call completes, which is required
+    /// to keep nested reentrant fee-paying calls from polluting each other. Per EIP-1153, a revert in the inner
+    /// call also reverts the transient write, so no explicit cleanup on the failure path is needed.
+    /// @dev Backfills `block.chainid` into the chain-bits half of the encoding when the caller passed a bare
+    /// project ID (non-zero project, zero chain). This lets callers write `referralProjectId: someProjectId`
+    /// without manually packing their own chain ID — the entry point resolves it to the current execution chain,
+    /// so storage and indexers always see a fully-resolved `(chainId, projectId)` pair.
+    /// @param referralProjectId The new value to write into the transient slot.
+    /// @return prior The value previously stored in the slot.
+    function _setReferralProjectId(uint256 referralProjectId) private returns (uint256 prior) {
+        if (referralProjectId != 0 && referralProjectId >> 48 == 0) {
+            referralProjectId |= block.chainid << 48;
+        }
+        prior = currentReferralProjectId;
+        currentReferralProjectId = referralProjectId;
+    }
 }

package/src/JBTerminalStore.sol

@@ -91,6 +91,26 @@ contract JBTerminalStore is IJBTerminalStore {
         public
         override balanceOf;
 
+    /// @notice Cumulative fee payment amount credited to a referrer (chainId, projectId) pair as a result of
+    /// fee-paying calls that originated through a given terminal.
+    /// @dev Written by terminals via `recordFeeReferralCreditOf`; the writing terminal is `msg.sender`, so a caller
+    /// can only pollute their own bucket.
+    /// @dev Nested by chain ID then project ID so off-chain consumers can read the credit for a specific
+    /// `(chainId, projectId)` directly without re-packing the encoded form themselves.
+    /// @custom:param terminal The terminal that originated the fee-paying call.
+    /// @custom:param referralChainId The EIP-155 chain ID of the referrer's home chain.
+    /// @custom:param referralProjectId The referrer's bare project ID on `referralChainId`.
+    mapping(address terminal => mapping(uint256 referralChainId => mapping(uint256 referralProjectId => uint256)))
+        public
+        override feeVolumeByReferralOf;
+
+    /// @notice Cumulative fee payment amount credited across all referral projects for a given terminal.
+    /// @dev Updated in lockstep with `feeVolumeByReferralOf` so consumers can compute a referrer's pro-rata share
+    /// in a single SLOAD pair without enumerating referrers. Used as the denominator by split hooks that distribute
+    /// rewards proportional to attributed fee volume.
+    /// @custom:param terminal The terminal that originated the fee-paying calls.
+    mapping(address terminal => uint256) public override totalFeeVolumeOf;
+
     /// @notice The currency-denominated amount of funds that a project has already paid out from its payout limit
     /// during the current ruleset for each terminal, in terms of the payout limit's currency.
     /// @dev Increases as projects pay out funds.
@@ -322,6 +342,22 @@ contract JBTerminalStore is IJBTerminalStore {
         }
     }
 
+    /// @notice Credit a referral project with a fee payment amount routed through `msg.sender` (the calling terminal).
+    /// @dev Called by `JBMultiTerminal._pay` after a payment lands on the fee project. Permissionless: writes are
+    /// scoped to `msg.sender`'s slots so an arbitrary caller can only pollute their own buckets — off-chain
+    /// consumers should filter on known terminal addresses. The amount is normalized to `NATIVE_TOKEN` units
+    /// (18 decimals) here in the store (where `PRICES` is available) so all credits share a common denominator.
+    /// @param referralProjectId The referral project to credit.
+    /// @param amount The fee amount paid by the originating fee-take call (raw value, decimals, currency).
+    function recordFeeReferralCreditOf(uint256 referralProjectId, JBTokenAmount calldata amount) external override {
+        _creditFeeReferral({
+            referralProjectId: referralProjectId,
+            amount: _normalizeToNativeTokenUnits({
+                value: amount.value, decimals: amount.decimals, currency: amount.currency
+            })
+        });
+    }
+
     /// @notice Records a payment — calculates how many project tokens to mint based on the payment amount and the
     /// current ruleset's weight. Uses the data hook if configured, otherwise mints proportionally.
     /// @dev Called by the terminal after accepting funds. Updates the project's recorded balance.
@@ -1378,4 +1414,79 @@ contract JBTerminalStore is IJBTerminalStore {
             }
         }
     }
+
+    //*********************************************************************//
+    // -------------------------- private helpers ------------------------ //
+    //*********************************************************************//
+
+    /// @notice Credit a referrer with a fee payment amount. Internal counterpart of `recordFeeReferralCreditOf` —
+    /// both write to the same slots and emit the same event.
+    /// @dev No-op when `referralProjectId == 0` or `amount == 0`.
+    /// @dev Unpacks the encoded `(chainId << 48) | projectId` form into the nested mapping at write-time so the
+    /// public getter exposes `(terminal, chainId, projectId) → cumulative` directly. The event topics carry the
+    /// two halves separately as well.
+    /// @param referralProjectId The packed `(chainId << 48) | projectId` referrer reference to credit.
+    /// @param amount The fee amount to credit.
+    function _creditFeeReferral(uint256 referralProjectId, uint256 amount) private {
+        if (referralProjectId == 0 || amount == 0) return;
+
+        uint256 referralChainId = referralProjectId >> 48;
+        uint256 bareProjectId = referralProjectId & ((1 << 48) - 1);
+
+        feeVolumeByReferralOf[msg.sender][referralChainId][bareProjectId] += amount;
+        uint256 newTotal = totalFeeVolumeOf[msg.sender] + amount;
+        totalFeeVolumeOf[msg.sender] = newTotal;
+
+        emit ReferralCredit({
+            terminal: msg.sender,
+            referralChainId: referralChainId,
+            referralProjectId: bareProjectId,
+            amount: amount,
+            newTotal: newTotal
+        });
+    }
+
+    /// @notice Normalize a fee-token amount to `JBConstants.NATIVE_TOKEN` units at 18 decimals.
+    /// @dev Two-step: first adjust decimals to 18 via `JBFixedPointNumber.adjustDecimals`, then convert currency
+    /// via `PRICES.pricePerUnitOf` using the fee project's price feeds. If no price feed exists for the pair, the
+    /// `try` block catches the revert and the credit is silently skipped — the payment itself still succeeds.
+    /// @param value The amount in the source token's native decimals.
+    /// @param decimals The source token's decimals.
+    /// @param currency The source token's accounting-context currency (`uint32(uint160(token))`).
+    /// @return normalized The amount expressed in `NATIVE_TOKEN` units (18 decimals), or 0 if conversion failed.
+    function _normalizeToNativeTokenUnits(
+        uint256 value,
+        uint256 decimals,
+        uint256 currency
+    )
+        private
+        view
+        returns (uint256 normalized)
+    {
+        // Adjust the source amount up/down to 18 decimals so all credits share a common precision.
+        normalized = decimals == _MAX_FIXED_POINT_FIDELITY
+            ? value
+            : JBFixedPointNumber.adjustDecimals({
+                value: value, decimals: decimals, targetDecimals: _MAX_FIXED_POINT_FIDELITY
+            });
+
+        if (normalized == 0 || currency == JBConstants.NATIVE_TOKEN_CURRENCY) return normalized;
+
+        // Convert from the source currency to NATIVE_TOKEN via the fee project's price feeds. A missing feed
+        // reverts inside `PRICES.pricePerUnitOf` — caught here so the payment is not blocked.
+        try PRICES.pricePerUnitOf({
+            projectId: JBConstants.FEE_BENEFICIARY_PROJECT_ID,
+            pricingCurrency: currency,
+            unitCurrency: JBConstants.NATIVE_TOKEN_CURRENCY,
+            decimals: _MAX_FIXED_POINT_FIDELITY
+        }) returns (
+            uint256 price
+        ) {
+            normalized = price == 0
+                ? 0
+                : mulDiv({x: normalized, y: 10 ** _MAX_FIXED_POINT_FIDELITY, denominator: price});
+        } catch {
+            normalized = 0;
+        }
+    }
 }

package/src/interfaces/IJBCashOutTerminal.sol

@@ -84,6 +84,8 @@ interface IJBCashOutTerminal is IJBTerminal {
     /// @param minTokensReclaimed The minimum number of terminal tokens that must be reclaimed.
     /// @param beneficiary The address to send the reclaimed terminal tokens to.
     /// @param metadata Extra data to send to the data hook and cash out hooks.
+    /// @param referralProjectId Optional project to credit with the protocol fee volume taken by this call. Pass `0`
+    /// to credit the project being cashed out.
     /// @return reclaimAmount The number of terminal tokens reclaimed from the project's surplus.
     function cashOutTokensOf(
         address holder,
@@ -92,7 +94,8 @@ interface IJBCashOutTerminal is IJBTerminal {
         address tokenToReclaim,
         uint256 minTokensReclaimed,
         address payable beneficiary,
-        bytes calldata metadata
+        bytes calldata metadata,
+        uint256 referralProjectId
     )
         external
         returns (uint256 reclaimAmount);

package/src/interfaces/IJBMultiTerminal.sol

@@ -30,4 +30,17 @@ interface IJBMultiTerminal is IJBTerminal, IJBFeeTerminal, IJBCashOutTerminal, I
 
     /// @notice The contract that manages token minting and burning.
     function TOKENS() external view returns (IJBTokens);
+
+    /// @notice The caller-originated referrer reference for the in-flight fee-paying external call.
+    /// @dev Encoded as `(referralChainId << 48) | referralProjectId`: bits [79:48] are the referrer's EIP-155 chain
+    /// ID (uint32), bits [47:0] are the referrer's project ID on that chain (uint48). Allows a referrer with a
+    /// project on chain X to be credited for activity on chain Y. A bare project ID (chain bits zero) is auto-
+    /// resolved to the current execution chain via `block.chainid` at the entry point, so storage and indexers
+    /// always see a fully-resolved `(chainId, projectId)` pair.
+    /// @dev Backed by transient storage. Set by `cashOutTokensOf`, `sendPayoutsOf`, and `useAllowanceOf` (save-
+    /// restore wrapper) so hooks invoked during that call (pay hooks, cashout hooks, split hooks) can introspect
+    /// which referrer originated the activity. Reads `0` outside any fee-paying call.
+    /// @dev Per-referrer cumulative fee payment amounts credited via this terminal are stored in
+    /// `JBTerminalStore.feeVolumeByReferralOf(address terminal, uint256 referralProjectId)`.
+    function currentReferralProjectId() external view returns (uint256);
 }

package/src/interfaces/IJBPayoutTerminal.sol

@@ -102,13 +102,16 @@ interface IJBPayoutTerminal is IJBTerminal {
     /// @param amount The total amount of tokens to pay out.
     /// @param currency The currency the amount is denominated in.
     /// @param minTokensPaidOut The minimum number of terminal tokens expected to be paid out.
+    /// @param referralProjectId Optional project to credit with the protocol fee volume taken by this call. Pass `0`
+    /// to credit the project sending payouts.
     /// @return amountPaidOut The total amount paid out.
     function sendPayoutsOf(
         uint256 projectId,
         address token,
         uint256 amount,
         uint256 currency,
-        uint256 minTokensPaidOut
+        uint256 minTokensPaidOut,
+        uint256 referralProjectId
     )
         external
         returns (uint256 amountPaidOut);
@@ -122,6 +125,8 @@ interface IJBPayoutTerminal is IJBTerminal {
     /// @param beneficiary The address to send the funds to.
     /// @param feeBeneficiary The address that will receive any project tokens minted from fees.
     /// @param memo A memo to pass along to the emitted event.
+    /// @param referralProjectId Optional project to credit with the protocol fee volume taken by this call. Pass `0`
+    /// to credit the project whose surplus allowance is being used.
     /// @return netAmountPaidOut The net amount paid out to the beneficiary after fees.
     function useAllowanceOf(
         uint256 projectId,
@@ -131,7 +136,8 @@ interface IJBPayoutTerminal is IJBTerminal {
         uint256 minTokensPaidOut,
         address payable beneficiary,
         address payable feeBeneficiary,
-        string calldata memo
+        string calldata memo,
+        uint256 referralProjectId
     )
         external
         returns (uint256 netAmountPaidOut);

package/src/interfaces/IJBTerminalStore.sol

@@ -15,6 +15,24 @@ import {JBTokenAmount} from "../structs/JBTokenAmount.sol";
 /// allowances, calculates token issuance per payment, and determines cash-out reclaim amounts via the bonding curve.
 /// Terminals delegate all state-changing accounting to this contract.
 interface IJBTerminalStore {
+    /// @notice Emitted when a referrer is credited with a fee payment amount.
+    /// @dev `referralChainId` and `referralProjectId` are emitted as separate indexed topics so off-chain consumers
+    /// can filter directly on either dimension. The `feeVolumeByReferralOf` storage key is the packed
+    /// `(referralChainId << 48) | referralProjectId` form — indexers re-pack the two fields when looking up the
+    /// cumulative balance for a referrer.
+    /// @param terminal The terminal that originated the fee-paying call (`msg.sender` on `recordFeeReferralCreditOf`).
+    /// @param referralChainId The EIP-155 chain ID of the referrer's home chain.
+    /// @param referralProjectId The referrer's bare project ID on `referralChainId` (no chain bits).
+    /// @param amount The fee amount credited, in the terminal's accounting-context units.
+    /// @param newTotal The new value of `totalFeeVolumeOf[terminal]` after this credit.
+    event ReferralCredit(
+        address indexed terminal,
+        uint256 indexed referralChainId,
+        uint256 indexed referralProjectId,
+        uint256 amount,
+        uint256 newTotal
+    );
+
     /// @notice The directory of terminals and controllers for projects.
     function DIRECTORY() external view returns (IJBDirectory);
 
@@ -142,6 +160,27 @@ interface IJBTerminalStore {
         view
         returns (uint256);
 
+    /// @notice The cumulative fee payment amount credited to a referrer (chainId, projectId) pair as a result of
+    /// fee-paying calls that originated through a given terminal.
+    /// @dev Written by terminals via `recordFeeReferralCreditOf` — `msg.sender` is recorded as the writing terminal,
+    /// so a malicious caller can only pollute their own slot. Off-chain consumers should filter on known terminal
+    /// addresses.
+    /// @dev Nested by chain ID then project ID so consumers can read the credit for a specific
+    /// `(chainId, projectId)` directly without re-packing the encoded form. The encoded `(chainId << 48) | projectId`
+    /// form is used only inside the transient slot and the entry-point parameter; storage exposes the unpacked pair.
+    /// @param terminal The terminal that originated the fee-paying call.
+    /// @param referralChainId The EIP-155 chain ID of the referrer's home chain.
+    /// @param referralProjectId The referrer's bare project ID on `referralChainId`.
+    /// @return The cumulative fee amount credited.
+    function feeVolumeByReferralOf(
+        address terminal,
+        uint256 referralChainId,
+        uint256 referralProjectId
+    )
+        external
+        view
+        returns (uint256);
+
     /// @notice Simulates a cash out without modifying state.
     /// @param terminal The terminal to simulate the cash out from.
     /// @param holder The address cashing out.
@@ -194,6 +233,13 @@ interface IJBTerminalStore {
         view
         returns (JBRuleset memory ruleset, uint256 tokenCount, JBPayHookSpecification[] memory hookSpecifications);
 
+    /// @notice The cumulative fee payment amount credited across all referral projects for a given terminal.
+    /// @dev Incremented in lockstep with `feeVolumeByReferralOf` so consumers can compute pro-rata shares in a
+    /// single SLOAD pair without enumerating referrers.
+    /// @param terminal The terminal that originated the fee-paying calls.
+    /// @return The cumulative total fee amount credited across all referrers for this terminal.
+    function totalFeeVolumeOf(address terminal) external view returns (uint256);
+
     /// @notice Returns the amount of payout limit used by a terminal for a project in a given cycle.
     /// @param terminal The terminal to get the used payout limit of.
     /// @param projectId The ID of the project.
@@ -269,6 +315,15 @@ interface IJBTerminalStore {
             JBCashOutHookSpecification[] memory hookSpecifications
         );
 
+    /// @notice Credit a referral project with a fee payment amount routed through `msg.sender` (the calling terminal).
+    /// @dev Permissionless: the write is scoped to `msg.sender`'s slot, so an arbitrary caller can only pollute
+    /// their own bucket. The amount is normalized to `JBConstants.NATIVE_TOKEN` units (18 decimals) using the fee
+    /// project's price feeds so credits across different fee tokens (ETH, USDC, USDT, …) are summable. No-op when
+    /// `referralProjectId == 0`, when `amount.value == 0`, or when no price feed exists for the pair.
+    /// @param referralProjectId The referral project to credit.
+    /// @param amount The fee amount paid by this fee-take call (raw token amount, decimals, and currency).
+    function recordFeeReferralCreditOf(uint256 referralProjectId, JBTokenAmount calldata amount) external;
+
     /// @notice Records a payment to a project.
     /// @param payer The address of the payer.
     /// @param amount The amount to pay.

package/src/libraries/JBConstants.sol

@@ -3,24 +3,34 @@ pragma solidity 0.8.28;
 
 /// @notice Protocol-wide constants. These define the boundaries for economic parameters throughout Juicebox.
 library JBConstants {
-    /// @notice The sentinel address used to represent each chain's native token (ETH on mainnet, etc.).
-    address public constant NATIVE_TOKEN = address(0x000000000000000000000000000000000000EEEe);
-
-    /// @notice The maximum reserved token percentage (basis points). 10,000 = 100% of minted tokens go to reserves.
-    uint16 public constant MAX_RESERVED_PERCENT = 10_000;
+    /// @notice The project ID that receives protocol fees. Project #1 is the protocol's own project; every
+    /// terminal forwards 2.5% of qualifying outflows to its primary fee terminal for this project.
+    uint256 public constant FEE_BENEFICIARY_PROJECT_ID = 1;
 
     /// @notice The maximum cash-out tax rate (basis points). 10,000 = 100% tax, meaning token holders reclaim nothing.
     uint16 public constant MAX_CASH_OUT_TAX_RATE = 10_000;
 
+    /// @notice The fee denominator. The protocol fee is `STANDARD_FEE / MAX_FEE`.
+    uint16 public constant MAX_FEE = 1000;
+
+    /// @notice The maximum reserved token percentage (basis points). 10,000 = 100% of minted tokens go to reserves.
+    uint16 public constant MAX_RESERVED_PERCENT = 10_000;
+
     /// @notice The maximum weight cut percent (9-decimal precision). 1,000,000,000 = 100% cut per cycle (no issuance).
     uint32 public constant MAX_WEIGHT_CUT_PERCENT = 1_000_000_000;
 
+    /// @notice The sentinel address used to represent each chain's native token (ETH on mainnet, etc.).
+    address public constant NATIVE_TOKEN = address(0x000000000000000000000000000000000000EEEe);
+
+    /// @notice The accounting-context currency identifier for `NATIVE_TOKEN`. Derived from `NATIVE_TOKEN`'s address
+    /// through the same cast (`uint32(uint160(token))`) that `JBAccountingContext.currency` uses, so a comparison
+    /// against this constant identifies the native-token currency without recomputing the cast at each call site.
+    // forge-lint: disable-next-line(unsafe-typecast)
+    uint32 public constant NATIVE_TOKEN_CURRENCY = uint32(uint160(NATIVE_TOKEN));
+
     /// @notice The denominator for split percentages (9-decimal precision). A split of 1,000,000,000 = 100%.
     uint32 public constant SPLITS_TOTAL_PERCENT = 1_000_000_000;
 
-    /// @notice The fee denominator. The protocol fee is `STANDARD_FEE / MAX_FEE`.
-    uint16 public constant MAX_FEE = 1000;
-
     /// @notice The standard protocol fee numerator. The protocol fee is `STANDARD_FEE / MAX_FEE` = 2.5%.
     uint16 public constant STANDARD_FEE = 25;
 }

package/src/libraries/JBHeldFees.sol

@@ -0,0 +1,170 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.28;
+
+import {IJBFeeTerminal} from "../interfaces/IJBFeeTerminal.sol";
+import {JBFee} from "../structs/JBFee.sol";
+import {JBFees} from "./JBFees.sol";
+
+/// @notice External-library implementation of held-fee storage operations for `JBMultiTerminal`.
+/// @dev Functions are `external` so they live in this library's deployed bytecode and are reached from the caller
+/// terminal via `DELEGATECALL`, keeping terminal bytecode below the EIP-170 limit. Storage refs are passed as
+/// parameters so the library reads/writes the caller's mappings.
+library JBHeldFees {
+    /// @notice Returns held fees back to a project's balance based on the specified incoming amount.
+    /// @dev Walks unprocessed held fees in storage order. For each fee, checks if the incoming `amount` covers
+    /// the original net payout (gross minus fee). If yes, the fee is fully credited back and the entry is
+    /// tombstoned by advancing the index. If only part of the fee can be refunded, the entry's stored gross
+    /// amount is shrunk in place using the back-calculated fee so a future top-up can still settle the remainder.
+    /// @dev Partial refunds use `standardFeeAmountResultingIn` so repaying a dust amount cannot both credit the
+    /// payer project and leave the fee project owed the 1-unit minimum fee. Reads `caller` from a parameter
+    /// instead of `msg.sender` because the library runs under `DELEGATECALL` from the terminal — `msg.sender`
+    /// here is the original external caller of the terminal, not the meta-tx-aware caller the terminal would
+    /// emit. The terminal passes `_msgSender()` so the event carries the meta-tx sender as intended.
+    /// @param heldFeesOf The terminal's held-fee storage mapping.
+    /// @param nextHeldFeeIndexOf The terminal's per-project/token next-index storage mapping.
+    /// @param projectId The project to return held fees to.
+    /// @param token The token that the held fees are in.
+    /// @param amount The incoming amount available to match against held fees.
+    /// @param caller The address that triggered the return, forwarded into the `ReturnHeldFees` event.
+    /// @return returnedFees The total fee amount returned to the project (sum of fully and partially refunded fees).
+    function returnHeldFees(
+        mapping(uint256 => mapping(address => JBFee[])) storage heldFeesOf,
+        mapping(uint256 => mapping(address => uint256)) storage nextHeldFeeIndexOf,
+        uint256 projectId,
+        address token,
+        uint256 amount,
+        address caller
+    )
+        external
+        returns (uint256 returnedFees)
+    {
+        // The first slot not yet returned, processed, or forgiven. Earlier slots are tombstones and skipped.
+        uint256 startIndex = nextHeldFeeIndexOf[projectId][token];
+
+        // Upper bound for the loop. Returning held fees never appends new entries, so the live length is fixed
+        // for the duration of this call.
+        uint256 numberOfHeldFees = heldFeesOf[projectId][token].length;
+
+        // No live entries — nothing to refund. Early return keeps the gas cost predictable for projects that
+        // never held a fee.
+        if (startIndex >= numberOfHeldFees) return 0;
+
+        // Tracks how much of the incoming `amount` is still available to match against further held fees as the
+        // loop consumes them. Initialized to the full incoming amount.
+        uint256 leftoverAmount = amount;
+
+        // Tracks how far the live-entry window has advanced. Only persisted if it actually moves, to avoid an
+        // unnecessary SSTORE when the loop ends without fully refunding any fee.
+        uint256 newStartIndex = startIndex;
+
+        for (uint256 i = startIndex; i < numberOfHeldFees;) {
+            // Stop early once the incoming amount has been fully consumed. Remaining held fees stay live and
+            // can be refunded by a future top-up.
+            if (leftoverAmount == 0) break;
+
+            // Snapshot the held fee into memory so subsequent reads (`.amount`) don't re-fetch from storage.
+            JBFee memory heldFee = heldFeesOf[projectId][token][i];
+
+            // Recompute the standard fee that was originally withheld from this entry's gross amount.
+            uint256 feeAmount = JBFees.standardFeeAmountFrom(heldFee.amount);
+
+            // The net amount that originally left the project after the fee was withheld — the deposit threshold
+            // this incoming amount must clear to fully release the fee.
+            uint256 amountPaidOut = heldFee.amount - feeAmount;
+
+            if (leftoverAmount >= amountPaidOut) {
+                // Full refund: the incoming amount covers everything the project paid out for this entry, so
+                // the whole fee comes back. Consume `amountPaidOut` from `leftoverAmount` and advance the
+                // tombstone window past this slot.
+                unchecked {
+                    leftoverAmount -= amountPaidOut;
+                    returnedFees += feeAmount;
+                }
+                newStartIndex = i + 1;
+            } else {
+                // Partial refund: only some of the original payout has been redeposited. Back-calculate the
+                // fee that corresponds to the remaining net amount (using `standardFeeAmountResultingIn` so
+                // the fee project never gets shorted on dust). Shrink the stored gross amount by both the
+                // refunded net and its fee, leaving the slot live so the leftover can be refunded later.
+                feeAmount = JBFees.standardFeeAmountResultingIn(leftoverAmount);
+                unchecked {
+                    // `JBFee.amount` is `uint224`; the subtraction operand is `uint256`. Narrow the operand to
+                    // `uint224` for the in-place update. The held gross amount was itself stored as `uint224`
+                    // and the partial refund is bounded above by it, so the narrowed subtrahend always fits.
+                    // forge-lint: disable-next-line(unsafe-typecast)
+                    heldFeesOf[projectId][token][i].amount -= uint224(leftoverAmount + feeAmount);
+                    returnedFees += feeAmount;
+                }
+                // All of the incoming amount has been matched — exit the loop next iteration.
+                leftoverAmount = 0;
+            }
+            unchecked {
+                ++i;
+            }
+        }
+
+        // Persist the new tombstone boundary only if any entry was fully refunded — partial refunds leave the
+        // boundary alone so they can be revisited.
+        if (startIndex != newStartIndex) nextHeldFeeIndexOf[projectId][token] = newStartIndex;
+
+        // Emit through the interface qualifier so the event topic matches what `IJBFeeTerminal` declares. The
+        // log surfaces under the calling terminal's address (we're inside its DELEGATECALL frame), so off-chain
+        // consumers filter on the terminal as usual.
+        emit IJBFeeTerminal.ReturnHeldFees({
+            projectId: projectId,
+            token: token,
+            amount: amount,
+            returnedFees: returnedFees,
+            leftoverAmount: leftoverAmount,
+            caller: caller
+        });
+    }
+
+    /// @notice Returns up to `count` held fees for a project/token, starting from the next unprocessed index.
+    /// @param heldFeesOf The terminal's held-fee storage mapping (project => token => array).
+    /// @param nextHeldFeeIndexOf The terminal's per-project/token next-index storage mapping.
+    /// @param projectId The ID of the project to read held fees for.
+    /// @param token The token the fees are denominated in.
+    /// @param count The maximum number of held fees to return.
+    /// @return heldFees A view-only copy of the unprocessed held fees, in storage order.
+    function viewHeldFees(
+        mapping(uint256 => mapping(address => JBFee[])) storage heldFeesOf,
+        mapping(uint256 => mapping(address => uint256)) storage nextHeldFeeIndexOf,
+        uint256 projectId,
+        address token,
+        uint256 count
+    )
+        external
+        view
+        returns (JBFee[] memory heldFees)
+    {
+        // The first slot not yet returned, processed, or forgiven. Slots before this are tombstones (zeroed by
+        // `processHeldFeesOf` / `returnHeldFees`) and must be skipped so callers only see live fees.
+        uint256 startIndex = nextHeldFeeIndexOf[projectId][token];
+
+        // Total entries ever appended for this project/token (live + tombstoned). Used as the upper bound when
+        // bounding `count`.
+        uint256 numberOfHeldFees = heldFeesOf[projectId][token].length;
+
+        // Nothing live to return — either the array was never populated, or every entry has already been processed
+        // since the last full-array delete. Return an empty array so callers can branch on `.length == 0`.
+        if (startIndex >= numberOfHeldFees) return new JBFee[](0);
+
+        // Cap `count` to the number of live entries so we don't index past `length`. Keeps the common
+        // "ask for more than there is" case from over-allocating the return buffer.
+        if (startIndex + count > numberOfHeldFees) count = numberOfHeldFees - startIndex;
+
+        // Allocate the return buffer at exactly the size we'll fill — saves the caller from filtering trailing
+        // empty entries.
+        heldFees = new JBFee[](count);
+
+        // Copy live entries from storage into the return buffer. `++i` is unchecked because `i < count` already
+        // bounds it well below `type(uint256).max`.
+        for (uint256 i; i < count;) {
+            heldFees[i] = heldFeesOf[projectId][token][startIndex + i];
+            unchecked {
+                ++i;
+            }
+        }
+    }
+}

package/src/structs/JBFee.sol

@@ -2,11 +2,22 @@
 pragma solidity ^0.8.0;
 
 /// @custom:member amount The total amount the fee was taken from, as a fixed point number with the same number of
-/// decimals as the token's accounting context.
+/// decimals as the token's accounting context. `uint224` covers any realistic per-call fee basis (max
+/// ~2.7e49 ETH-equivalent at 18 decimals) and is the same width the protocol's payout/surplus-allowance limits use.
+/// @custom:member referralChainId The EIP-155 chain ID of the referrer's home chain, captured from the upper bits of
+/// the transient referral encoding at fee-take time. A value of `0` is the "current chain" sentinel — a referrer that
+/// only encoded a project ID without a chain prefix is credited on the chain the fee is paid on. Packing this beside
+/// `amount` in the same storage slot avoids growing `JBFee` to a third slot.
 /// @custom:member beneficiary The address that will receive the tokens that are minted as a result of the fee payment.
 /// @custom:member unlockTimestamp The timestamp at which the fee is unlocked and can be processed.
+/// @custom:member referralProjectId The referrer's project ID on `referralChainId`. Captured from the lower bits of
+/// `currentReferralProjectId` at fee-take time so held-fee attribution survives the 28-day hold window. The on-chain
+/// transient slot, function argument, and `feeVolumeByReferralOf` mapping key all use the packed `uint256` form
+/// `(referralChainId << 48) | referralProjectId`; this struct stores the two halves separately for cheap storage.
 struct JBFee {
-    uint256 amount;
+    uint224 amount;
+    uint32 referralChainId;
     address beneficiary;
     uint48 unlockTimestamp;
+    uint48 referralProjectId;
 }

package/test/mock/MockMaliciousBeneficiary.sol

@@ -18,7 +18,8 @@ contract MaliciousPayoutBeneficiary is IERC721Receiver, Test {
             amount: 5 * 10 ** 18,
             currency: uint32(uint160(JBConstants.NATIVE_TOKEN)),
             token: JBConstants.NATIVE_TOKEN,
-            minTokensPaidOut: 0
+            minTokensPaidOut: 0,
+            referralProjectId: 0
         });
         assertEq(_reentrantPayout, 0);
     }
@@ -49,7 +50,8 @@ contract MaliciousAllowanceBeneficiary is IERC721Receiver, Test {
             minTokensPaidOut: 0,
             beneficiary: payable(address(this)),
             feeBeneficiary: payable(0x000000000000000000000000000000000000007B),
-            memo: "MEMO"
+            memo: "MEMO",
+            referralProjectId: 0
         });
     }