@bananapus/core-v6 0.0.58 → 0.0.60

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
         });
     }
 

package/CHANGELOG.md

@@ -1,73 +0,0 @@
-# Changelog
-
-## Scope
-
-This file describes the verified change from `nana-core-v5` to the current `nana-core-v6` repo.
-
-## Current v6 surface
-
-- `JBController`
-- `JBMultiTerminal`
-- `JBTerminalStore`
-- `JBRulesets`
-- `JBTokens`
-- the shared core interfaces, structs, and libraries under `src/`
-
-## Summary
-
-- v6 adds explicit preview APIs for pay and cash-out flows. Integrations can simulate more of the terminal path directly from the core contracts.
-- Token metadata is more editable than in v5. The controller now exposes a dedicated token-metadata update path.
-- Approval-hook handling is safer. The v6 codebase and tests are built around preventing a bad approval hook from freezing project behavior.
-- Fee accounting is tighter than in v5, especially around fee-free surplus behavior and cross-flow bookkeeping.
-- The repo carries much broader test coverage than the v5 tree, including dedicated review, invariant, fork, and formal-style suites.
-- The implementation baseline moved from the v5 `0.8.23` world to `0.8.28`.
-
-## Verified deltas
-
-- `IJBTerminal.previewPayFor(...)` is new.
-- `IJBCashOutTerminal.previewCashOutFrom(...)` and `IJBTerminalStore.previewCashOutFrom(...)` are new preview surfaces.
-- `IJBController.setTokenMetadataOf(uint256,string,string)` is new.
-- `IJBController.addPriceFeed(...)` became `addPriceFeedFor(...)`.
-- `IJBTerminal.currentSurplusOf(...)` now takes `address[] calldata tokens` instead of the old accounting-context array input.
-- The interface surface adds explicit hook-spec return types to preview flows, which changes what off-chain callers can and should decode.
-
-## Breaking ABI changes
-
-- `IJBController.addPriceFeed(...)` was renamed to `addPriceFeedFor(...)`.
-- `IJBController.setTokenMetadataOf(...)` is new and sits on the core controller surface.
-- `IJBController.previewMintOf(...)` is new.
-- `IJBTerminal.previewPayFor(...)` is new.
-- `IJBCashOutTerminal.previewCashOutFrom(...)` is new.
-- `IJBTerminalStore.previewPayFrom(...)` and `previewCashOutFrom(...)` are new.
-- `IJBTerminal.currentSurplusOf(...)` changed parameter shape.
-
-## Indexer impact
-
-- `SplitHookReverted` is a new controller event.
-- Preview functions do not emit events, but they change what frontends and simulation services can derive without sending transactions.
-- If your indexer inferred token metadata immutability from v5, that assumption is no longer safe once `setTokenMetadataOf(...)` is in use.
-
-## Migration notes
-
-- Rebuild against the v6 interfaces. This repo is too central for hand-maintained ABI diffs to be trustworthy.
-- Review any integration that assumed old ruleset-cache behavior, old preview availability, or old token-metadata immutability.
-- If your system relied on subtle fee-free cash-out behavior from v5, re-validate it against the v6 accounting model.
-
-## ABI appendix
-
-- Added functions
-  - `IJBTerminal.previewPayFor(...)`
-  - `IJBCashOutTerminal.previewCashOutFrom(...)`
-  - `IJBTerminalStore.previewPayFrom(...)`
-  - `IJBTerminalStore.previewCashOutFrom(...)`
-  - `IJBController.previewMintOf(...)`
-  - `IJBController.setTokenMetadataOf(...)`
-- Renamed functions
-  - `IJBController.addPriceFeed(...)` -> `addPriceFeedFor(...)`
-- Changed function shapes
-  - `IJBTerminal.currentSurplusOf(...)`
-- Added events
-  - `SplitHookReverted`
-- Added migration-sensitive capabilities
-  - mutable token metadata
-  - preview-oriented hook-spec decoding

package/foundry.lock

@@ -1,5 +0,0 @@
-{
-  "lib/forge-std": {
-    "rev": "726a6ee5fc8427a0013d6f624e486c9130c0e336"
-  }
-}