@bananapus/core-v6 0.0.46 → 0.0.47

package/package.json

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

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,

package/src/JBTerminalStore.sol

@@ -427,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];
 

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,