@bananapus/core-v6 0.0.45 → 0.0.47

package/package.json

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

package/references/types-errors-events.md

@@ -79,7 +79,7 @@ Use this file when you need deeper protocol reference material after the repo-lo
 - `pricePerUnitOf()` is on `IJBPrices`, NOT `IJBController` -- access via `IJBController(ctrl).PRICES().pricePerUnitOf(...)`
 - `JBRulesetConfig` fields need explicit casts: `uint48 mustStartAtOrAfter`, `uint32 duration`, `uint112 weight`, `uint32 weightCutPercent`
 - Zero-amount `pay{value:0}()` and zero-count `cashOutTokensOf(count=0)` are valid no-ops (mint/return 0)
-- `sendPayoutsOf()` reverts when `amount > payout limit` -- does NOT auto-cap
+- `sendPayoutsOf()` auto-caps `amount` to the remaining payout limit -- does NOT revert. Use `minTokensPaidOut` to enforce a minimum.
 - `IJBTokens.claimTokensFor()` takes 4 args: `(holder, projectId, count, beneficiary)` -- NOT 3
 - `JBFeelessAddresses.setFeelessAddress()` NOT `setIsFeelessAddress()` -- the function name omits "Is"
 - Named returns auto-return (no explicit `return` statement needed in Solidity)
@@ -105,7 +105,7 @@ Use this file when you need deeper protocol reference material after the repo-lo
 - `IJBDirectoryAccessControl` has `setControllerAllowed()` and `setTerminalsAllowed()` -- NOT `setControllerAllowedFor()`
 - Price feeds are immutable once set in `JBPrices` -- they cannot be replaced or removed
 - `JBFundAccessLimits` requires payout limits and surplus allowances to be in strictly increasing currency order to prevent duplicates
-- **Empty `fundAccessLimitGroups` = zero payouts, NOT unlimited.** If a ruleset's `fundAccessLimitGroups` array is empty (or has no entry for the terminal/token), `payoutLimitsOf()` returns an empty array → cumulative limit is 0 → `sendPayoutsOf()` reverts on any amount. To allow unlimited payouts, explicitly set a payout limit with `amount: type(uint224).max`.
+- **Empty `fundAccessLimitGroups` = zero payouts, NOT unlimited.** If a ruleset's `fundAccessLimitGroups` array is empty (or has no entry for the terminal/token), `payoutLimitsOf()` returns an empty array → cumulative limit is 0 → `sendPayoutsOf()` caps to 0 and returns 0. To allow unlimited payouts, explicitly set a payout limit with `amount: type(uint224).max`.
 - **`groupId` (uint256) vs `currency` (uint32) are different types for the same address.** `JBSplitGroup.groupId` is `uint256(uint160(tokenAddress))` while `JBAccountingContext.currency` is `uint32(uint160(tokenAddress))`. These truncate differently — only `NATIVE_TOKEN` (0x000000000000000000000000000000000000EEEe) matches by coincidence. Don't confuse them.
 - **`JBAccountingContext.currency` is NOT `baseCurrency` — by design.** `baseCurrency` in ruleset metadata uses abstract real-world values (1 = ETH, 2 = USD) so rulesets are portable across chains — `baseCurrency=2` means "issue X tokens per USD" whether on Ethereum, Base, or Arbitrum. `JBAccountingContext.currency` uses token-derived values (`uint32(uint160(tokenAddress))`) because terminals track specific tokens at specific addresses — e.g. NATIVE_TOKEN = 61166, USDC on Ethereum = 909516616, USDC on Base = 3169378579. `JBPrices` mediates between the two: it converts token-derived currencies to/from abstract currencies (e.g. USDC token → USD concept, NATIVE_TOKEN → ETH concept) so that payout limits denominated in USD work correctly regardless of which token the terminal holds. The separation is what makes cross-chain consistency possible: same ruleset, different terminal accounting per chain.
 - **Don't queue multiple identical rulesets.** A ruleset with a `duration` automatically cycles — no need to queue copies. Queue multiple rulesets only when configuration actually changes between periods (e.g. different weight, splits, or limits).
@@ -166,7 +166,7 @@ Errors an agent is most likely to encounter. All are custom errors (revert with
 | `JBMultiTerminal_PermitAllowanceNotEnough` | `JBMultiTerminal` | Permit2 allowance insufficient for the payment amount. |
 | `JBTerminalStore_RulesetPaymentPaused` | `JBTerminalStore` | `pausePay` is set in the current ruleset. |
 | `JBTerminalStore_RulesetNotFound` | `JBTerminalStore` | No ruleset exists for the project (not launched). |
-| `JBTerminalStore_InadequateControllerPayoutLimit` | `JBTerminalStore` | `sendPayoutsOf` amount exceeds the payout limit for this cycle. |
+
 | `JBTerminalStore_InadequateControllerAllowance` | `JBTerminalStore` | `useAllowanceOf` amount exceeds the surplus allowance. |
 | `JBTerminalStore_InadequateTerminalStoreBalance` | `JBTerminalStore` | Withdrawal exceeds the terminal's recorded balance. |
 | `JBTerminalStore_InsufficientTokens` | `JBTerminalStore` | Cash out count exceeds the holder's token balance. |

package/src/JBController.sol

@@ -238,12 +238,12 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
         }
     }
 
-    /// @notice Burns a holder's project tokens (or credits), permanently removing them from supply. Used by terminals
-    /// during cash outs, or directly by holders who want to burn voluntarily.
+    /// @notice Burns a holder's project tokens (or unclaimed credits), permanently removing them from the project
+    /// token supply. Used by terminals during cash outs, or directly by holders who want to burn voluntarily.
     /// @dev Can only be called by the holder, an operator with `BURN_TOKENS` permission, or a project terminal.
-    /// @param holder The address to burn tokens for.
-    /// @param projectId The ID of the project to burn tokens for.
-    /// @param tokenCount The number of tokens to burn.
+    /// @param holder The address whose project tokens (or credits) are being burned.
+    /// @param projectId The ID of the project whose tokens are being burned.
+    /// @param tokenCount The number of project tokens (or credits) to burn, as a fixed point number with 18 decimals.
     /// @param memo A memo to pass along to the emitted event.
     function burnTokensOf(
         address holder,
@@ -273,13 +273,16 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
         TOKENS.burnFrom({holder: holder, projectId: projectId, count: tokenCount});
     }
 
-    /// @notice Converts internal credits into the project's ERC-20 token, transferring them to the beneficiary's
-    /// wallet. Credits and ERC-20 tokens are interchangeable — this just makes them transferable/tradeable.
+    /// @notice Converts a holder's internal project token credits into the project's ERC-20 representation,
+    /// transferring them to the beneficiary's wallet. Credits and the ERC-20 are equivalent project tokens — this
+    /// just
+    /// makes them transferable/tradeable.
     /// @dev Can only be called by the credit holder or an operator with `CLAIM_TOKENS` permission.
-    /// @param holder The address to redeem credits from.
-    /// @param projectId The ID of the project to claim tokens for.
-    /// @param tokenCount The number of tokens to claim.
-    /// @param beneficiary The account the claimed tokens will go to.
+    /// @param holder The address whose project token credits are being redeemed.
+    /// @param projectId The ID of the project whose project tokens are being claimed.
+    /// @param tokenCount The number of project token credits to convert into ERC-20 project tokens, as a fixed point
+    /// number with 18 decimals.
+    /// @param beneficiary The account that receives the resulting ERC-20 project tokens.
     function claimTokensFor(
         address holder,
         uint256 projectId,
@@ -520,12 +523,14 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
     /// reserved percent (which accumulates until `sendReservedTokensToSplitsOf` is called).
     /// @dev Can be called by the project owner, an operator with `MINT_TOKENS` permission, a project terminal, or the
     /// data hook. If `allowOwnerMinting` is false in the current ruleset, only terminals and the data hook can mint.
-    /// @param projectId The ID of the project to mint tokens for.
-    /// @param tokenCount The number of tokens to mint, including any reserved tokens.
-    /// @param beneficiary The address which will receive the (non-reserved) tokens.
+    /// @param projectId The ID of the project whose project tokens are being minted.
+    /// @param tokenCount The total number of project tokens to mint (the beneficiary's share plus the reserved share if
+    /// `useReservedPercent` is true), as a fixed point number with 18 decimals.
+    /// @param beneficiary The address that receives the non-reserved portion of the minted project tokens.
     /// @param memo A memo to pass along to the emitted event.
     /// @param useReservedPercent Whether to apply the ruleset's reserved percent.
-    /// @return beneficiaryTokenCount The number of tokens minted for the `beneficiary`.
+    /// @return beneficiaryTokenCount The number of project tokens minted to `beneficiary` (excluding the reserved
+    /// share), as a fixed point number with 18 decimals.
     function mintTokensOf(
         uint256 projectId,
         uint256 tokenCount,

package/src/JBMultiTerminal.sol

@@ -220,14 +220,15 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         }
     }
 
-    /// @notice Adds funds to a project's balance without minting tokens. Useful for topping up a project or returning
-    /// funds. Can also unlock previously held fees by returning them to the project's balance.
+    /// @notice Adds funds (terminal tokens) to a project's balance without minting project tokens. Useful for topping
+    /// up a project or returning funds. Can also unlock previously held fees by returning them to the project's
+    /// balance.
     /// @dev If `shouldReturnHeldFees` is true, the added amount offsets held fees proportionally.
     /// @param projectId The ID of the project to add funds to the balance of.
-    /// @param amount The amount of tokens to add to the balance, as a fixed point number with the same number of
-    /// decimals as the token's accounting context. If this is a native token terminal, this is ignored and `msg.value`
-    /// is used instead.
-    /// @param token The token to add to the balance.
+    /// @param token The terminal token being added (the ERC-20, or `JBConstants.NATIVE_TOKEN` for native).
+    /// @param amount The amount of the terminal `token` to add, as a fixed point number with the same number of
+    /// decimals as the token's accounting context. If `token` is the native token, this argument is ignored and
+    /// `msg.value` is used instead.
     /// @param shouldReturnHeldFees If true, return held fees proportional to the amount added.
     /// @param memo A memo to pass along to the emitted event.
     /// @param metadata Extra data to pass along to the emitted event.
@@ -254,24 +255,25 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         });
     }
 
-    /// @notice Cash out project tokens. The project's current ruleset determines the reclaimed surplus and any data
-    /// hook or cash out hook behavior.
-    /// @dev Only the token holder or an operator with `CASH_OUT_TOKENS` permission from that holder can call this.
-    /// @param holder The account cashing out tokens.
+    /// @notice Burn project tokens to reclaim a share of the project's surplus (held as a terminal token). The
+    /// project's current ruleset determines the reclaimed amount, plus any data hook or cash out hook behavior.
+    /// @dev Only the project token holder, or an operator with `CASH_OUT_TOKENS` permission from that holder, can call
+    /// this.
+    /// @dev Two distinct tokens are involved: **project tokens** (`cashOutCount`) are burned from `holder`, and
+    /// **terminal tokens** (`tokenToReclaim`) are sent to `beneficiary` in exchange.
+    /// @param holder The account whose project tokens are being burned.
     /// @param projectId The ID of the project the project tokens belong to.
-    /// @param cashOutCount The number of project tokens to cash out and burn, as a fixed point number with 18
-    /// decimals.
-    /// @param tokenToReclaim The token to reclaim.
-    /// @param minTokensReclaimed The minimum number of terminal tokens expected in return, as a fixed point number with
-    /// the same number of decimals as the token's accounting context. If the amount of tokens minted for the
-    /// beneficiary would be less than this amount, the cash out is reverted.
-    /// @param beneficiary The address to send the cashed out terminal tokens to, and to pass along to the ruleset's
+    /// @param cashOutCount The number of project tokens to burn, as a fixed point number with 18 decimals.
+    /// @param tokenToReclaim The terminal token to reclaim from the project's surplus.
+    /// @param minTokensReclaimed The minimum number of terminal tokens that must be returned to `beneficiary` for the
+    /// call to succeed, as a fixed point number with the same number of decimals as the terminal token's accounting
+    /// context. If fewer terminal tokens would be reclaimed, the cash out is reverted.
+    /// @param beneficiary The address to send the reclaimed terminal tokens to, and to pass along to the ruleset's
     /// 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.
-    /// @return reclaimAmount The amount of terminal tokens that the project tokens were cashed out for, as a fixed
-    /// point
-    /// number with 18 decimals.
+    /// @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(
         address holder,
         uint256 projectId,
@@ -565,22 +567,25 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         }
     }
 
-    /// @notice Pay a project. The project's current ruleset determines how many project tokens the beneficiary receives
-    /// and any data hook or pay hook behavior.
+    /// @notice Pay a project with a payment token. The project's ruleset determines how many project tokens the
+    /// beneficiary receives, plus any data hook or pay hook behavior.
+    /// @dev Two distinct tokens are involved: the **payment token** (`token`, e.g. ETH or an ERC-20) flows from the
+    /// payer into the terminal, and **project tokens** (the project's own ERC-20 / credit balance) are minted to the
+    /// `beneficiary` according to the ruleset's weight.
     /// @param projectId The ID of the project to pay.
-    /// @param amount The amount of tokens to send, as a fixed point number with the same number of
-    /// decimals as the token's accounting context. If this terminal's token is native, this is ignored and `msg.value`
-    /// is used in its place.
-    /// @param token The token to pay with.
-    /// @param beneficiary The address to mint tokens to, and pass along to the ruleset's data hook and pay hook if
-    /// applicable.
-    /// @param minReturnedTokens The minimum number of project tokens expected in return for this payment, as a fixed
-    /// point number with the same number of decimals as the token's accounting context. If the amount of tokens minted
-    /// for the beneficiary would be less than this amount, the payment is reverted.
+    /// @param token The payment token to pay with (the ERC-20, or `JBConstants.NATIVE_TOKEN` for native).
+    /// @param amount The amount of the payment `token` to send, as a fixed point number with the same number of
+    /// decimals as the token's accounting context. If `token` is the native token, this argument is ignored and
+    /// `msg.value` is used in its place.
+    /// @param beneficiary The address to mint project tokens to, and to pass along to the ruleset's data hook and pay
+    /// hook if applicable.
+    /// @param minReturnedTokens The minimum number of project tokens the beneficiary must receive for the payment to
+    /// succeed, as a fixed point number with 18 decimals. If fewer project tokens would be minted, the payment is
+    /// reverted.
     /// @param memo A memo to pass along to the emitted event.
     /// @param metadata Bytes to pass along to the emitted event, as well as the data hook and pay hook if applicable.
-    /// @return beneficiaryTokenCount The number of tokens minted to the beneficiary, as a fixed point number with 18
-    /// decimals.
+    /// @return beneficiaryTokenCount The number of **project tokens** minted to `beneficiary`, as a fixed point number
+    /// with 18 decimals.
     function pay(
         uint256 projectId,
         address token,
@@ -728,21 +733,23 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     /// @notice Withdraws funds from a project's surplus (beyond what's needed for payouts) up to the current ruleset's
     /// surplus allowance. Sent directly to a beneficiary address rather than through splits.
     /// @dev Only the project's owner or an operator with `USE_ALLOWANCE` permission can call this.
-    /// @dev Incurs the 2.5% protocol fee unless the caller is a feeless address.
+    /// @dev Incurs the 2.5% protocol fee unless the caller is a feeless address. The fee is charged in the terminal
+    /// token (`token`); the fee project mints **project tokens** in return and sends them to `feeBeneficiary`.
     /// @param projectId The ID of the project to use the surplus allowance of.
-    /// @param token The token to pay out from the surplus.
-    /// @param amount The amount of terminal tokens to use from the project's current surplus allowance, as a fixed
+    /// @param token The terminal token to pay out from the surplus.
+    /// @param amount The amount of terminal `token` to use from the project's current surplus allowance, as a fixed
     /// point number with the same number of decimals as the token's accounting context.
-    /// @param currency The expected currency of the amount to pay out. Must match the currency of one of the
-    /// project's current ruleset's surplus allowances.
-    /// @param minTokensPaidOut The minimum number of terminal tokens that should be returned from the surplus allowance
-    /// (excluding fees), as a fixed point number with 18 decimals. If the amount of surplus used would be less than
-    /// this amount, the transaction is reverted.
-    /// @param beneficiary The address to send the surplus funds to.
-    /// @param feeBeneficiary The address to send the tokens resulting from paying the fee.
+    /// @param currency The expected currency of `amount`. Must match the currency of one of the project's current
+    /// ruleset's surplus allowances.
+    /// @param minTokensPaidOut The minimum number of terminal tokens that must be returned from the surplus allowance
+    /// (excluding fees), as a fixed point number with the same number of decimals as the terminal token's accounting
+    /// context. If less would be paid out, the transaction is reverted.
+    /// @param beneficiary The address to send the reclaimed terminal tokens to.
+    /// @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.
-    /// @return netAmountPaidOut The number of tokens that were sent to the beneficiary, as a fixed point number with
-    /// the same number of decimals as the token's accounting context.
+    /// @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(
         uint256 projectId,
         address token,
@@ -1815,6 +1822,9 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         (ruleset, amountPaidOut) =
             STORE.recordPayoutFor({projectId: projectId, token: token, amount: amount, currency: currency});
 
+        // If nothing to pay out (e.g. payout limit already used or not configured), return early.
+        if (amountPaidOut == 0) return amountPaidOut;
+
         // Get a reference to the project's owner.
         // The owner will receive tokens minted by paying the platform fee and receive any leftover funds not sent to
         // payout splits.

package/src/JBTerminalStore.sol

@@ -45,7 +45,7 @@ contract JBTerminalStore is IJBTerminalStore {
     );
     error JBTerminalStore_AddingAccountingContextNotAllowed(uint256 projectId, uint256 rulesetId, address terminal);
     error JBTerminalStore_InadequateControllerAllowance(uint256 amount, uint256 allowance);
-    error JBTerminalStore_InadequateControllerPayoutLimit(uint256 amount, uint256 limit);
+
     error JBTerminalStore_InadequateTerminalStoreBalance(uint256 amount, uint256 balance);
     error JBTerminalStore_InsufficientTokens(uint256 count, uint256 totalSupply);
     error JBTerminalStore_InvalidAmountToForwardHook(uint256 amount, uint256 paidAmount);
@@ -392,6 +392,26 @@ contract JBTerminalStore is IJBTerminalStore {
         // Get a reference to the project's current ruleset.
         ruleset = RULESETS.currentOf(projectId);
 
+        // Get the payout limit for this currency.
+        uint256 payoutLimit = IJBController(address(DIRECTORY.controllerOf(projectId))).FUND_ACCESS_LIMITS()
+            .payoutLimitOf({
+            projectId: projectId, rulesetId: ruleset.id, terminal: msg.sender, token: token, currency: currency
+        });
+
+        // Get the already-used payout limit for this cycle.
+        uint256 usedPayoutLimit = usedPayoutLimitOf[msg.sender][projectId][token][ruleset.cycleNumber][currency];
+
+        // Cap the amount to the remaining payout limit instead of reverting.
+        uint256 remainingPayoutLimit = payoutLimit > usedPayoutLimit ? payoutLimit - usedPayoutLimit : 0;
+        if (amount > remainingPayoutLimit) {
+            amount = remainingPayoutLimit;
+        }
+
+        // If nothing can be paid out, return early with zero.
+        if (amount == 0) {
+            return (ruleset, 0);
+        }
+
         // Convert the amount to the balance's currency.
         amountPaidOut = (currency == accountingContext.currency)
             ? amount
@@ -407,6 +427,13 @@ contract JBTerminalStore is IJBTerminalStore {
                 })
             });
 
+        // If cross-currency conversion rounded to zero, return without consuming any payout limit. Otherwise a
+        // permissionless caller could repeatedly request sub-unit payouts to drain the cycle's payout limit
+        // without moving any funds.
+        if (amountPaidOut == 0) {
+            return (ruleset, 0);
+        }
+
         // Cache the balance slot to avoid redundant storage reads.
         uint256 currentBalance = balanceOf[msg.sender][projectId][token];
 
@@ -415,29 +442,13 @@ contract JBTerminalStore is IJBTerminalStore {
             revert JBTerminalStore_InadequateTerminalStoreBalance({amount: amountPaidOut, balance: currentBalance});
         }
 
-        // The new total amount which has been paid out during this ruleset.
-        uint256 newUsedPayoutLimitOf =
-            usedPayoutLimitOf[msg.sender][projectId][token][ruleset.cycleNumber][currency] + amount;
-
-        // Amount must be within what is still available to pay out.
-        // Validate BEFORE writing to storage to avoid wasting gas on SSTORE when the tx will revert.
-        uint256 payoutLimit = IJBController(address(DIRECTORY.controllerOf(projectId))).FUND_ACCESS_LIMITS()
-            .payoutLimitOf({
-            projectId: projectId, rulesetId: ruleset.id, terminal: msg.sender, token: token, currency: currency
-        });
-
-        // Make sure the new used amount is within the payout limit.
-        if (newUsedPayoutLimitOf > payoutLimit || payoutLimit == 0) {
-            revert JBTerminalStore_InadequateControllerPayoutLimit({amount: newUsedPayoutLimitOf, limit: payoutLimit});
-        }
-
         // Removed the paid out funds from the project's token balance.
         unchecked {
             balanceOf[msg.sender][projectId][token] = currentBalance - amountPaidOut;
         }
 
         // Store the new used payout limit.
-        usedPayoutLimitOf[msg.sender][projectId][token][ruleset.cycleNumber][currency] = newUsedPayoutLimitOf;
+        usedPayoutLimitOf[msg.sender][projectId][token][ruleset.cycleNumber][currency] = usedPayoutLimit + amount;
     }
 
     /// @notice Records a terminal migration — zeros out the project's balance and returns the amount moved to

package/src/interfaces/IJBCashOutTerminal.sol

@@ -75,16 +75,16 @@ interface IJBCashOutTerminal is IJBTerminal {
             JBCashOutHookSpecification[] memory hookSpecifications
         );
 
-    /// @notice Cashes out a holder's tokens for a project, reclaiming the token's proportional share of the project's
-    /// surplus.
-    /// @param holder The address cashing out tokens.
-    /// @param projectId The ID of the project cashing out tokens.
-    /// @param cashOutCount The number of project tokens to cash out.
-    /// @param tokenToReclaim The token to reclaim from the project's surplus.
-    /// @param minTokensReclaimed The minimum number of terminal tokens expected to be reclaimed.
-    /// @param beneficiary The address to send the reclaimed tokens to.
+    /// @notice Burn a holder's project tokens to reclaim a proportional share of the project's surplus (paid out as a
+    /// terminal token).
+    /// @param holder The address whose project tokens are being burned.
+    /// @param projectId The ID of the project whose project tokens are being burned.
+    /// @param cashOutCount The number of project tokens to burn.
+    /// @param tokenToReclaim The terminal token to reclaim from the project's surplus.
+    /// @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.
-    /// @return reclaimAmount The amount of tokens reclaimed from the project's surplus.
+    /// @return reclaimAmount The number of terminal tokens reclaimed from the project's surplus.
     function cashOutTokensOf(
         address holder,
         uint256 projectId,

package/src/interfaces/IJBController.sol

@@ -261,18 +261,18 @@ interface IJBController is IERC165, IJBProjectUriRegistry, IJBDirectoryAccessCon
     )
         external;
 
-    /// @notice Burns a holder's project tokens or credits.
-    /// @param holder The address to burn tokens for.
-    /// @param projectId The ID of the project to burn tokens for.
-    /// @param tokenCount The number of tokens to burn.
+    /// @notice Burns a holder's project tokens or unclaimed project token credits, removing them from supply.
+    /// @param holder The address whose project tokens (or credits) are being burned.
+    /// @param projectId The ID of the project whose project tokens are being burned.
+    /// @param tokenCount The number of project tokens (or credits) to burn.
     /// @param memo A memo to pass along to the emitted event.
     function burnTokensOf(address holder, uint256 projectId, uint256 tokenCount, string calldata memo) external;
 
-    /// @notice Redeems credits to claim tokens into a beneficiary's account.
-    /// @param holder The address to redeem credits from.
-    /// @param projectId The ID of the project to claim tokens for.
-    /// @param tokenCount The number of tokens to claim.
-    /// @param beneficiary The account the claimed tokens will go to.
+    /// @notice Converts project token credits into the project's ERC-20 representation, sending them to a beneficiary.
+    /// @param holder The address whose project token credits are being redeemed.
+    /// @param projectId The ID of the project whose project tokens are being claimed.
+    /// @param tokenCount The number of project token credits to convert into ERC-20 project tokens.
+    /// @param beneficiary The account that receives the resulting ERC-20 project tokens.
     function claimTokensFor(address holder, uint256 projectId, uint256 tokenCount, address beneficiary) external;
 
     /// @notice Deploys an ERC-20 token for a project.
@@ -324,13 +324,16 @@ interface IJBController is IERC165, IJBProjectUriRegistry, IJBDirectoryAccessCon
         external
         returns (uint256 rulesetId);
 
-    /// @notice Mints new project tokens or credits to a beneficiary, optionally reserving a portion.
-    /// @param projectId The ID of the project to mint tokens for.
-    /// @param tokenCount The number of tokens to mint, including any reserved tokens.
-    /// @param beneficiary The address which will receive the non-reserved tokens.
+    /// @notice Mints new project tokens (or credits) to a beneficiary, optionally reserving a portion for the ruleset's
+    /// reserved splits.
+    /// @param projectId The ID of the project whose project tokens are being minted.
+    /// @param tokenCount The total number of project tokens to mint (the beneficiary's share plus the reserved share if
+    /// `useReservedPercent` is true).
+    /// @param beneficiary The address that receives the non-reserved portion of the minted project tokens.
     /// @param memo A memo to pass along to the emitted event.
     /// @param useReservedPercent Whether to apply the ruleset's reserved percent.
-    /// @return beneficiaryTokenCount The number of tokens minted for the beneficiary.
+    /// @return beneficiaryTokenCount The number of project tokens minted to `beneficiary` (excluding the reserved
+    /// share).
     function mintTokensOf(
         uint256 projectId,
         uint256 tokenCount,

package/src/interfaces/IJBTerminal.sol

@@ -137,10 +137,10 @@ interface IJBTerminal is IERC165 {
     /// @param accountingContexts The accounting contexts to add.
     function addAccountingContextsFor(uint256 projectId, JBAccountingContext[] calldata accountingContexts) external;
 
-    /// @notice Adds funds to a project's balance.
+    /// @notice Adds terminal tokens to a project's balance (no project tokens are minted).
     /// @param projectId The ID of the project to add funds to.
-    /// @param token The token added.
-    /// @param amount The amount of tokens added.
+    /// @param token The terminal token being added.
+    /// @param amount The amount of terminal `token` being added.
     /// @param shouldReturnHeldFees Whether held fees should be returned based on the amount added.
     /// @param memo A memo to pass along to the emitted event.
     /// @param metadata Extra data to pass along to the emitted event.
@@ -162,15 +162,15 @@ interface IJBTerminal is IERC165 {
     /// @return balance The amount of funds that were migrated.
     function migrateBalanceOf(uint256 projectId, address token, IJBTerminal to) external returns (uint256 balance);
 
-    /// @notice Pays a project in a specified token.
+    /// @notice Pay a project with a payment token in exchange for project tokens minted to a beneficiary.
     /// @param projectId The ID of the project to pay.
-    /// @param token The token to pay with.
-    /// @param amount The amount of tokens to pay.
+    /// @param token The payment token to pay with.
+    /// @param amount The amount of the payment `token` to pay.
     /// @param beneficiary The address to mint project tokens to.
-    /// @param minReturnedTokens The minimum number of project tokens expected in return.
+    /// @param minReturnedTokens The minimum number of project tokens the beneficiary must receive.
     /// @param memo A memo to pass along to the emitted event.
     /// @param metadata Extra data to pass along to the pay hooks.
-    /// @return beneficiaryTokenCount The number of tokens minted for the beneficiary.
+    /// @return beneficiaryTokenCount The number of project tokens minted to the beneficiary.
     function pay(
         uint256 projectId,
         address token,

package/test/mock/MockMaliciousBeneficiary.sol

@@ -11,13 +11,8 @@ import {IERC721Receiver} from "@openzeppelin/contracts/token/ERC721/IERC721Recei
 /// @dev Attempts to re-enter sendPayoutsOf after receiving control-flow.
 contract MaliciousPayoutBeneficiary is IERC721Receiver, Test {
     function reEnter(address _terminal) internal {
-        vm.expectRevert(
-            abi.encodeWithSelector(
-                JBTerminalStore.JBTerminalStore_InadequateControllerPayoutLimit.selector, 1.5e19, 10 * 10 ** 18
-            )
-        );
-
-        IJBMultiTerminal(_terminal)
+        // Reentrancy attempt — payout limit already used, so the cap returns 0 (no funds extracted).
+        uint256 _reentrantPayout = IJBMultiTerminal(_terminal)
             .sendPayoutsOf({
             projectId: 2,
             amount: 5 * 10 ** 18,
@@ -25,6 +20,7 @@ contract MaliciousPayoutBeneficiary is IERC721Receiver, Test {
             token: JBConstants.NATIVE_TOKEN,
             minTokensPaidOut: 0
         });
+        assertEq(_reentrantPayout, 0);
     }
 
     receive() external payable {