@bananapus/core-v6 0.0.68 → 0.0.70

package/package.json

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

package/references/types-errors-events.md

@@ -89,7 +89,7 @@ Use this file when you need deeper protocol reference material after the repo-lo
 - `JBERC20` is cloned via `Clones.clone()` -- its constructor sets invalid name/symbol; real values set in `initialize()`
 - Fee is 2.5% (`FEE = 25` out of `MAX_FEE = 1000`)
 - Project #1 is the fee beneficiary project (receives all protocol fees)
-- **Fee-free cashout exemption is scoped to fee-free intra-terminal payout amounts.** `_feeFreeSurplusOf[projectId][token]` accumulates the value of fee-free payouts. After any outflow (payouts, `useAllowanceOf`, non-zero-tax or feeless cashouts), the counter is capped at the remaining balance — non-fee-free funds leave first, preserving the fee-free counter. During cashout with `cashOutTaxRate=0`, the 2.5% fee applies only up to this surplus, then depletes. Once consumed, subsequent cashouts are fee-free again. Cleared on terminal migration. This prevents a round-trip fee bypass (intra-terminal payout → zero-tax cashout) while scoping fees precisely to the fee-free inflow.
+- **Fee-free cashout exemption is scoped to fee-free intra-terminal payout amounts.** `feeFreeSurplusOf[projectId][token]` accumulates the value of fee-free payouts. After any outflow (payouts, `useAllowanceOf`, non-zero-tax or feeless cashouts), the counter is capped at the remaining balance — non-fee-free funds leave first, preserving the fee-free counter. During cashout with `cashOutTaxRate=0`, the 2.5% fee applies only up to this surplus, then depletes. Once consumed, subsequent cashouts are fee-free again. Cleared on terminal migration. This prevents a round-trip fee bypass (intra-terminal payout → zero-tax cashout) while scoping fees precisely to the fee-free inflow.
 - `JBProjects` constructor optionally mints project #1 to `feeProjectOwner` -- if `address(0)`, no fee project is created
 - `JBMultiTerminal` derives `DIRECTORY` from the provided `store` in its constructor -- not passed directly
 - `JBPrices.pricePerUnitOf()` checks project direct feeds, project inverse feeds, default direct feeds, then default inverse feeds. It skips feeds that revert or return zero.

package/src/JBMultiTerminal.sol

@@ -111,7 +111,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     IJBTokens public immutable override TOKENS;
 
     //*********************************************************************//
-    // --------------------- internal stored properties ------------------ //
+    // --------------------- public stored properties -------------------- //
     //*********************************************************************//
 
     /// @notice The cumulative amount of fee-free intra-terminal payouts a project has received for a given token.
@@ -126,7 +126,11 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     /// unconsumed balance. There is no admin function to reset it.
     /// @custom:param projectId The ID of the project that received the payout.
     /// @custom:param token The token that was received.
-    mapping(uint256 projectId => mapping(address token => uint256)) internal _feeFreeSurplusOf;
+    mapping(uint256 projectId => mapping(address token => uint256)) public override feeFreeSurplusOf;
+
+    //*********************************************************************//
+    // --------------------- internal stored properties ------------------ //
+    //*********************************************************************//
 
     /// @notice Fees currently held for each project.
     /// @dev Projects can temporarily hold fees and unlock them later by adding funds to the project's balance.
@@ -447,7 +451,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
 
                 // Same-terminal adds never invoke destination pay hooks, so the full amount remains in the
                 // destination project's balance and must be fee-liable on its later zero-tax cashout.
-                if (isThisTerminal) _feeFreeSurplusOf[split.projectId][token] += netPayoutAmount;
+                if (isThisTerminal) feeFreeSurplusOf[split.projectId][token] += netPayoutAmount;
             } else {
                 // Keep a reference to the beneficiary of the payment.
                 address beneficiary = split.beneficiary != address(0) ? split.beneficiary : originalMessageSender;
@@ -592,7 +596,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         }
 
         // Clear fee-free surplus tracking — the fee-free liability is settled by the migration fee below.
-        delete _feeFreeSurplusOf[projectId][token];
+        delete feeFreeSurplusOf[projectId][token];
 
         // Terminal migration intentionally does not transfer held fees. Held fees belong to the
         // fee beneficiary (project #1), not the migrating project. They unlock after 28 days regardless of terminal.
@@ -672,7 +676,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         returns (uint256 beneficiaryTokenCount)
     {
         // Get a reference to the beneficiary's balance before the payment.
-        uint256 beneficiaryBalanceBefore = TOKENS.totalBalanceOf({holder: beneficiary, projectId: projectId});
+        uint256 beneficiaryBalanceBefore = _totalBalanceOf({holder: beneficiary, projectId: projectId});
 
         // Accept the funds.
         uint256 acceptedAmount =
@@ -690,7 +694,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         });
 
         // Get a reference to the beneficiary's balance after the payment.
-        uint256 beneficiaryBalanceAfter = TOKENS.totalBalanceOf({holder: beneficiary, projectId: projectId});
+        uint256 beneficiaryBalanceAfter = _totalBalanceOf({holder: beneficiary, projectId: projectId});
 
         // Set the beneficiary token count.
         if (beneficiaryBalanceAfter > beneficiaryBalanceBefore) {
@@ -1213,7 +1217,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     /// @param token The token whose fee-free surplus to cap.
     function _capFeeFreeSurplus(uint256 projectId, address token) internal {
         // Get the current fee-free surplus for this project/token pair.
-        uint256 feeFreeSurplus = _feeFreeSurplusOf[projectId][token];
+        uint256 feeFreeSurplus = feeFreeSurplusOf[projectId][token];
 
         // Nothing to cap if there's no fee-free surplus tracked.
         if (feeFreeSurplus == 0) return;
@@ -1223,7 +1227,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
 
         // Cap fee-free surplus at the remaining balance.
         if (feeFreeSurplus > remainingBalance) {
-            _feeFreeSurplusOf[projectId][token] = remainingBalance;
+            feeFreeSurplusOf[projectId][token] = remainingBalance;
         }
     }
 
@@ -1300,11 +1304,11 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
                     }
                 } else {
                     // Zero tax: fees apply only up to the fee-free surplus (round-trip prevention).
-                    uint256 feeFreeSurplus = _feeFreeSurplusOf[projectId][tokenToReclaim];
+                    uint256 feeFreeSurplus = feeFreeSurplusOf[projectId][tokenToReclaim];
                     if (feeFreeSurplus != 0) {
                         uint256 feeableAmount = reclaimAmount < feeFreeSurplus ? reclaimAmount : feeFreeSurplus;
                         unchecked {
-                            _feeFreeSurplusOf[projectId][tokenToReclaim] = feeFreeSurplus - feeableAmount;
+                            feeFreeSurplusOf[projectId][tokenToReclaim] = feeFreeSurplus - feeableAmount;
                         }
                         amountEligibleForFees += feeableAmount;
                         unchecked {
@@ -1338,7 +1342,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             });
         }
 
-        // Cap fee-free surplus after every cash-out path so stale `_feeFreeSurplusOf` cannot survive after
+        // Cap fee-free surplus after every cash-out path so stale `feeFreeSurplusOf` cannot survive after
         // associated surplus leaves. Do this after hook fulfillment so hook-driven balance reductions are included.
         _capFeeFreeSurplus({projectId: projectId, token: tokenToReclaim});
 
@@ -1788,7 +1792,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
                     ++i;
                 }
             }
-            _feeFreeSurplusOf[projectId][token] += feeFreeAmount;
+            feeFreeSurplusOf[projectId][token] += feeFreeAmount;
         }
 
         // Keep a reference to the number of tokens issued for the beneficiary.
@@ -1885,7 +1889,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             _recordAddedBalanceFor({projectId: projectId, token: token, amount: amount});
             // The store balance was credited first; this mirrors that bounded increase for fee recovery.
             unchecked {
-                _feeFreeSurplusOf[projectId][token] += amount;
+                feeFreeSurplusOf[projectId][token] += amount;
             }
         }
     }
@@ -2320,6 +2324,14 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             JBTokenAmount({token: token, decimals: context.decimals, currency: context.currency, value: value});
     }
 
+    /// @notice Returns a holder's total token balance for a project.
+    /// @param holder The holder to get a balance for.
+    /// @param projectId The ID of the project to get a balance for.
+    /// @return balance The holder's total project token balance.
+    function _totalBalanceOf(address holder, uint256 projectId) internal view returns (uint256 balance) {
+        return TOKENS.totalBalanceOf({holder: holder, projectId: projectId});
+    }
+
     //*********************************************************************//
     // -------------------------- private helpers ------------------------ //
     //*********************************************************************//

package/src/interfaces/IJBMultiTerminal.sol

@@ -43,4 +43,14 @@ interface IJBMultiTerminal is IJBTerminal, IJBFeeTerminal, IJBCashOutTerminal, I
     /// @dev Per-referrer cumulative fee payment amounts credited via this terminal are stored in
     /// `JBTerminalStore.feeVolumeByReferralOf(address terminal, uint256 referralChainId, uint256 referralProjectId)`.
     function currentReferralProjectId() external view returns (uint256);
+
+    /// @notice The cumulative amount of fee-free intra-terminal payouts a project has received for a given token.
+    /// @dev Incremented each time a fee-free payout lands (same terminal, no fee charged) and consumed during
+    /// zero-tax cash outs to prevent a round-trip fee bypass (intra-terminal payout -> zero-tax cash out). Exposed
+    /// for off-chain indexers and integrating contracts that need to reason about a project's outstanding fee-free
+    /// exposure before performing related operations.
+    /// @param projectId The ID of the project that received the payout.
+    /// @param token The token that was received.
+    /// @return The cumulative unconsumed fee-free surplus tracked for the (project, token) pair.
+    function feeFreeSurplusOf(uint256 projectId, address token) external view returns (uint256);
 }