@bananapus/core-v6 0.0.38 → 0.0.40

package/src/JBMultiTerminal.sol

@@ -45,8 +45,13 @@ import {JBSplit} from "./structs/JBSplit.sol";
 import {JBSplitHookContext} from "./structs/JBSplitHookContext.sol";
 import {JBTokenAmount} from "./structs/JBTokenAmount.sol";
 
-/// @notice `JBMultiTerminal` manages native/ERC-20 payments, cash outs, and surplus allowance usage for any number of
-/// projects. Terminals are the entry point for operations involving inflows and outflows of funds.
+/// @notice The main entry point for all money movement in Juicebox. Handles payments (ETH or ERC-20), cash outs
+/// (burning tokens to reclaim funds), payouts (distributing funds to splits), and surplus allowance withdrawals.
+/// Charges a 2.5% protocol fee on outflows (held for 28 days before processing). Supports Permit2 for gasless
+/// ERC-20 approvals.
+/// @dev Each project can have multiple terminals for different tokens. The terminal delegates accounting to
+/// `JBTerminalStore` and splits distribution to `JBSplits`. Fees are sent to project #1 (the fee beneficiary).
+/// All external hook calls (pay hooks, cash-out hooks, split hooks) are wrapped in try-catch to prevent griefing.
 contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     // A library that parses the packed ruleset metadata into a friendlier format.
     using JBRulesetMetadataResolver for JBRuleset;
@@ -99,10 +104,10 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     /// @notice The directory of terminals and controllers for PROJECTS.
     IJBDirectory public immutable override DIRECTORY;
 
-    /// @notice The contract that stores addresses that shouldn't incur fees when being paid towards or from.
+    /// @notice The contract that stores addresses that shouldn't incur fees when paid towards or from.
     IJBFeelessAddresses public immutable override FEELESS_ADDRESSES;
 
-    /// @notice The permit2 utility.
+    /// @notice The Permit2 contract used for token approvals and transfers.
     IPermit2 public immutable override PERMIT2;
 
     /// @notice Mints ERC-721s that represent project ownership and transfers.
@@ -135,23 +140,23 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     /// @custom:param token The token that was received.
     mapping(uint256 projectId => mapping(address token => uint256)) internal _feeFreeSurplusOf;
 
-    /// @notice Fees that are being held for each project.
+    /// @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.
     /// @dev Held fees can be processed at any time by this terminal's owner.
-    /// @custom:param projectId The ID of the project that is holding fees.
-    /// @custom:param token The token that the fees are held in.
+    /// @custom:param projectId The ID of the project holding fees.
+    /// @custom:param token The token the fees are held in.
     mapping(uint256 projectId => mapping(address token => JBFee[])) internal _heldFeesOf;
 
     /// @notice The next index to use when processing a next held fee.
-    /// @custom:param projectId The ID of the project that is holding fees.
-    /// @custom:param token The token that the fees are held in.
+    /// @custom:param projectId The ID of the project holding fees.
+    /// @custom:param token The token the fees are held in.
     mapping(uint256 projectId => mapping(address token => uint256)) internal _nextHeldFeeIndexOf;
 
     //*********************************************************************//
     // -------------------------- constructor ---------------------------- //
     //*********************************************************************//
 
-    /// @param feelessAddresses A contract that stores addresses that shouldn't incur fees when being paid towards or
+    /// @param feelessAddresses A contract that stores addresses that shouldn't incur fees when paid towards or
     /// from.
     /// @param permissions A contract storing permissions.
     /// @param projects A contract which mints ERC-721s that represent project ownership and transfers.
@@ -185,10 +190,10 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     // ---------------------- external transactions ---------------------- //
     //*********************************************************************//
 
-    /// @notice Adds accounting contexts for a project to this terminal so the project can begin accepting the tokens in
-    /// those contexts.
-    /// @dev Only a project's owner, an operator with the `ADD_ACCOUNTING_CONTEXTS` permission from that owner, or a
-    /// project's controller can add accounting contexts for the project.
+    /// @notice Registers new tokens that this terminal can accept for a project. Once a token's accounting context is
+    /// added, the project can receive payments in that token.
+    /// @dev Only the project's owner, an operator with `ADD_ACCOUNTING_CONTEXTS` permission, or the project's
+    /// controller can call this.
     /// @param projectId The ID of the project having to add accounting contexts for.
     /// @param accountingContexts The accounting contexts to add.
     function addAccountingContextsFor(
@@ -219,13 +224,14 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         }
     }
 
-    /// @notice Adds funds to a project's balance without minting tokens.
-    /// @dev Adding to balance can unlock held fees if `shouldUnlockHeldFees` is true.
+    /// @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.
+    /// @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 this terminal. If this is a native token terminal, this is ignored and `msg.value` is used instead.
-    /// @param token The token being added to the balance.
-    /// @param shouldReturnHeldFees A flag indicating if held fees should be returned based on the amount being added.
+    /// @param token The token to add to the balance.
+    /// @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.
     function addToBalanceOf(
@@ -251,15 +257,14 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         });
     }
 
-    /// @notice Holders can cash out a project's tokens to reclaim some of that project's surplus tokens, or to trigger
-    /// rules determined by the current ruleset's data hook and cash out hook.
-    /// @dev Only a token's holder or an operator with the `CASH_OUT_TOKENS` permission from that holder can cash out
-    /// those tokens.
-    /// @param holder The account whose tokens are being cashed out.
+    /// @notice Burns project tokens to reclaim a share of the project's surplus (determined by the bonding curve) or
+    /// to trigger custom logic through the ruleset's data hook and cash out hook.
+    /// @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.
     /// @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 being reclaimed.
+    /// @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 this terminal. If the amount of tokens minted for the beneficiary would be less
     /// than this amount, the cash out is reverted.
@@ -303,8 +308,8 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     /// @dev Only accepts calls from this terminal itself.
     /// @param split The split to pay.
     /// @param projectId The ID of the project the split belongs to.
-    /// @param token The address of the token being paid to the split.
-    /// @param amount The total amount being paid to the split, as a fixed point number with the same number of
+    /// @param token The address of the token to pay to the split.
+    /// @param amount The total amount to pay to the split, as a fixed point number with the same number of
     /// decimals as this terminal.
     /// @return netPayoutAmount The amount sent to the split after subtracting fees.
     function executePayout(
@@ -452,7 +457,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     /// @notice Process a specified amount of fees for a project.
     /// @dev Only accepts calls from this terminal itself.
     /// @param projectId The ID of the project paying the fee.
-    /// @param token The token the fee is being paid in.
+    /// @param token The token the fee is paid in.
     /// @param amount The fee amount, as a fixed point number with 18 decimals.
     /// @param beneficiary The address to mint tokens to (from the project which receives fees), and pass along to the
     /// ruleset's data hook and pay hook if applicable.
@@ -501,9 +506,9 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     /// @notice Migrate a project's funds and operations to a new terminal that accepts the same token type.
     /// @dev Only a project's owner or an operator with the `MIGRATE_TERMINAL` permission from that owner can migrate
     /// the project's terminal.
-    /// @param projectId The ID of the project being migrated.
-    /// @param token The address of the token being migrated.
-    /// @param to The terminal contract being migrated to, which will receive the project's funds and operations.
+    /// @param projectId The ID of the project to migrate.
+    /// @param token The address of the token to migrate.
+    /// @param to The terminal to migrate to, which will receive the project's funds and operations.
     /// @return balance The amount of funds that were migrated, as a fixed point number with the same amount of decimals
     /// as this terminal.
     function migrateBalanceOf(
@@ -563,12 +568,13 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         }
     }
 
-    /// @notice Pay a project with tokens.
-    /// @param projectId The ID of the project being paid.
-    /// @param amount The amount of terminal tokens being received, as a fixed point number with the same number of
+    /// @notice Pay a project with tokens. The project's current ruleset determines how many project tokens the
+    /// beneficiary will receive.
+    /// @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 this terminal. If this terminal's token is native, this is ignored and `msg.value` is used in its
     /// place.
-    /// @param token The token being paid.
+    /// @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
@@ -622,19 +628,13 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         _checkMin({value: beneficiaryTokenCount, min: minReturnedTokens});
     }
 
-    /// @notice Process any fees that are being held for the project.
-    /// @dev Reentrancy safety: the loop re-reads `_nextHeldFeeIndexOf` from storage each iteration and advances the
-    /// index before the external `_processFee` call, so a reentrant call cannot double-process the same fee entry.
-    /// @dev Held fees after migration: held fees remain in this terminal after `migrateBalanceOf` because their backing
-    /// tokens are not part of `balanceOf` — they were already deducted from the recorded balance during the payout
-    /// that
-    /// created them. The actual fee-backing tokens remain in this terminal's token holdings. If `_processFee` reverts
-    /// (e.g. the fee terminal rejects the payment), the catch block calls `_recordAddedBalanceFor` to credit the fee
-    /// amount back to the project. This credit is backed by the tokens that failed to transfer out. No phantom balance
-    /// is created because the tokens never left.
-    /// @dev The index-increment-before-`_processFee` pattern is intentional: locked (not-yet-unlocked) fees are skipped
-    /// via the `unlockTimestamp` check, and advancing the index before the external call prevents reentrancy from
-    /// reprocessing the same fee entry.
+    /// @notice Processes held fees for a project, sending them to the protocol's fee project. Fees are held for 28 days
+    /// after a payout — processing them finalizes the fee payment.
+    /// @dev Only processes fees whose `unlockTimestamp` has passed. Stops early if it encounters a still-locked fee.
+    /// @dev Reentrancy-safe: re-reads `_nextHeldFeeIndexOf` from storage each iteration and advances the index before
+    /// the external `_processFee` call, preventing double-processing.
+    /// @dev If `_processFee` reverts (fee terminal rejects), the fee amount is returned to the project's balance
+    /// (forgiven, not retried). A `FeeReverted` event is emitted for off-chain observability.
     /// @param projectId The ID of the project to process held fees for.
     /// @param token The token to process held fees for.
     /// @param count The number of fees to process.
@@ -657,6 +657,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
 
             // Can't process fees that aren't yet unlocked. Fees unlock sequentially in the array, so nothing left to do
             // if the current fee isn't yet unlocked.
+            // forge-lint: disable-next-line(block-timestamp)
             if (heldFee.unlockTimestamp > block.timestamp) break;
 
             // Delete the entry and advance the index *before* the external call. This is intentional:
@@ -694,20 +695,17 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         }
     }
 
-    /// @notice Sends payouts to a project's current payout split group, according to its ruleset, up to its current
-    /// payout limit.
-    /// @dev If the percentages of the splits in the project's payout split group do not add up to 100%, the remainder
-    /// is sent to the project's owner.
-    /// @dev Anyone can send payouts on a project's behalf. Projects can include a wildcard split (a split with no
-    /// `hook`, `projectId`, or `beneficiary`) to send funds to the `_msgSender()` which calls this function. This can
-    /// be used to incentivize calling this function.
-    /// @dev payouts sent to addresses which aren't feeless incur the protocol fee.
-    /// @dev Payouts a projects don't incur fees if its terminal is feeless.
+    /// @notice Distributes funds from a project's balance to its payout split recipients, up to the current ruleset's
+    /// payout limit. Anyone can call this on behalf of any project.
+    /// @dev If splits don't add up to 100%, the remainder goes to the project owner. A wildcard split (no hook,
+    /// projectId, or beneficiary) sends its share to `msg.sender` — useful for incentivizing the call.
+    /// @dev Payouts to non-feeless addresses incur the 2.5% protocol fee. Projects whose terminal is feeless are
+    /// exempt.
     /// @param projectId The ID of the project having its payouts sent.
-    /// @param token The token being sent.
+    /// @param token The token to send.
     /// @param amount The total number of terminal tokens to send, as a fixed point number with same number of decimals
     /// as this terminal.
-    /// @param currency The expected currency of the payouts being sent. Must match the currency of one of the
+    /// @param currency The expected currency of the payouts. Must match the currency of one of the
     /// project's current ruleset's payout limits.
     /// @param minTokensPaidOut The minimum number of terminal tokens that the `amount` should be worth (if expressed
     /// in terms of this terminal's currency), as a fixed point number with the same number of decimals as this
@@ -730,15 +728,15 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         _checkMin({value: amountPaidOut, min: minTokensPaidOut});
     }
 
-    /// @notice Allows a project to pay out funds from its surplus up to the current surplus allowance.
-    /// @dev Only a project's owner or an operator with the `USE_ALLOWANCE` permission from that owner can use the
-    /// surplus allowance.
-    /// @dev Incurs the protocol fee unless the caller is a feeless address.
+    /// @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.
     /// @param projectId The ID of the project to use the surplus allowance of.
-    /// @param token The token being paid out from the surplus.
+    /// @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
     /// point number with the same amount of decimals as this terminal.
-    /// @param currency The expected currency of the amount being paid out. Must match the currency of one of the
+    /// @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
@@ -787,8 +785,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     // ------------------------- external views -------------------------- //
     //*********************************************************************//
 
-    /// @notice A project's accounting context for a token.
-    /// @dev See the `JBAccountingContext` struct for more information.
+    /// @notice Returns the accounting context (decimals, currency) for a specific token that a project accepts.
     /// @param projectId The ID of the project to get token accounting context of.
     /// @param token The token to check the accounting context of.
     /// @return The token's accounting context for the token.
@@ -804,15 +801,16 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         return STORE.accountingContextOf({terminal: address(this), projectId: projectId, token: token});
     }
 
-    /// @notice The tokens accepted by a project.
+    /// @notice Returns accounting contexts for all tokens a project currently accepts through this terminal.
     /// @param projectId The ID of the project to get the accepted tokens of.
     /// @return tokenContexts The accounting contexts of the accepted tokens.
     function accountingContextsOf(uint256 projectId) external view override returns (JBAccountingContext[] memory) {
         return STORE.accountingContextsOf({terminal: address(this), projectId: projectId});
     }
 
-    /// @notice Gets the current surplus amount in this terminal for a project, in terms of a given currency.
-    /// @dev If `tokens` is empty, includes all tokens the project accepts (as returned by `accountingContextsOf(...)`).
+    /// @notice Returns the project's current surplus in this terminal, converted to a specified currency. The surplus
+    /// is the balance minus what's needed for payout limits.
+    /// @dev If `tokens` is empty, includes all tokens the project accepts.
     /// @param projectId The ID of the project to get the current surplus of.
     /// @param tokens The tokens to include in the surplus calculation. If empty, all tokens are included.
     /// @param decimals The number of decimals to include in the fixed point returned value.
@@ -837,11 +835,12 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         });
     }
 
-    /// @notice Fees that are being held for a project.
-    /// @dev Projects can temporarily hold fees and unlock them later by adding funds to the project's balance.
-    /// @dev Held fees can be processed at any time by this terminal's owner.
-    /// @param projectId The ID of the project that is holding fees.
-    /// @param token The token that the fees are held in.
+    /// @notice Returns the fees currently held for a project. Fees are held for 28 days after a payout before
+    /// they can be processed (sent to the fee project).
+    /// @dev Held fees can be returned to the project by calling `addToBalanceOf` with `shouldReturnHeldFees = true`
+    /// before the 28-day lock expires.
+    /// @param projectId The ID of the project holding fees.
+    /// @param token The token the fees are held in.
     /// @param count The maximum number of held fees to return.
     /// @return heldFees The held fees.
     function heldFeesOf(
@@ -878,9 +877,10 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         }
     }
 
-    /// @notice Simulates cashing out project tokens from this terminal without modifying state.
-    /// @param holder The address whose tokens are being cashed out.
-    /// @param projectId The ID of the project whose tokens are being cashed out.
+    /// @notice Simulates a cash out without modifying state — use this to preview how many tokens a holder would
+    /// reclaim.
+    /// @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 beneficiary The address that would receive the reclaimed tokens.
@@ -919,10 +919,12 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             });
     }
 
-    /// @notice Simulates paying a project through this terminal without modifying state.
-    /// @param projectId The ID of the project being paid.
-    /// @param token The token being paid in.
-    /// @param amount The amount of tokens being paid.
+    /// @notice Simulates a payment without modifying state — use this to preview how many project tokens a payer
+    /// would
+    /// receive.
+    /// @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 beneficiary The address to mint project tokens to.
     /// @param metadata Extra data to pass along to the data hook and pay hooks.
     /// @return ruleset The project's current ruleset.
@@ -984,9 +986,9 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     //*********************************************************************//
 
     /// @notice Accepts an incoming token.
-    /// @param projectId The ID of the project that the transfer is being accepted for.
-    /// @param token The token being accepted.
-    /// @param amount The number of tokens being accepted.
+    /// @param projectId The ID of the project to accept the transfer for.
+    /// @param token The token to accept.
+    /// @param amount The number of tokens to accept.
     /// @param metadata The metadata in which permit2 context is provided.
     /// @return amount The number of tokens which have been accepted.
     function _acceptFundsFor(
@@ -1050,10 +1052,10 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
 
     /// @notice Adds funds to a project's balance without minting tokens.
     /// @param projectId The ID of the project to add funds to the balance of.
-    /// @param token The address of the token being added to the project's balance.
+    /// @param token The address of the token to add to the project's balance.
     /// @param amount The amount of tokens to add as a fixed point number with the same number of decimals as this
     /// terminal. If this is a native token terminal, this is ignored and `msg.value` is used instead.
-    /// @param shouldReturnHeldFees A flag indicating if held fees should be returned based on the amount being added.
+    /// @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.
     function _addToBalanceOf(
@@ -1086,10 +1088,10 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
 
     /// @notice Logic to be triggered before transferring tokens from this terminal.
     /// @param to The address the transfer is going to.
-    /// @param token The token being transferred.
-    /// @param amount The number of tokens being transferred, as a fixed point number with the same number of decimals
+    /// @param token The token to transfer.
+    /// @param amount The number of tokens to transfer, as a fixed point number with the same number of decimals
     /// as this terminal.
-    /// @return payValue The value to attach to the transaction being sent.
+    /// @return payValue The value to attach to the transaction.
     function _beforeTransferTo(address to, address token, uint256 amount) internal returns (uint256) {
         // If the token is the native token, no allowance needed, and the full amount should be used as the payValue.
         if (token == JBConstants.NATIVE_TOKEN) return amount;
@@ -1129,9 +1131,9 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     /// those
     /// tokens.
     /// @param holder The account cashing out tokens.
-    /// @param projectId The ID of the project whose tokens are being cashed out.
+    /// @param projectId The ID of the project cashing out tokens.
     /// @param cashOutCount The number of project tokens to cash out, as a fixed point number with 18 decimals.
-    /// @param tokenToReclaim The address of the token which is being cashed out.
+    /// @param tokenToReclaim The address of the token to reclaim.
     /// @param beneficiary The address to send the reclaimed terminal tokens to.
     /// @param metadata Bytes to send along to the emitted event, as well as the data hook and cash out hook if
     /// applicable.
@@ -1279,9 +1281,9 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     /// @notice Fund a project either by calling this terminal's internal `addToBalance` function or by calling the
     /// recipient terminal's `addToBalance` function.
     /// @param terminal The terminal on which the project is expecting to receive funds.
-    /// @param projectId The ID of the project being funded.
-    /// @param token The token being used.
-    /// @param amount The amount being funded, as a fixed point number with the amount of decimals that the terminal's
+    /// @param projectId The ID of the project to fund.
+    /// @param token The token to use.
+    /// @param amount The amount to fund, as a fixed point number with the amount of decimals that the terminal's
     /// accounting context specifies.
     /// @param metadata Additional metadata to include with the payment.
     function _efficientAddToBalance(
@@ -1314,9 +1316,9 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     /// @notice Pay a project either by calling this terminal's internal `pay` function or by calling the recipient
     /// terminal's `pay` function.
     /// @param terminal The terminal on which the project is expecting to receive payments.
-    /// @param projectId The ID of the project being paid.
-    /// @param token The token being paid in.
-    /// @param amount The amount being paid, as a fixed point number with the amount of decimals that the terminal's
+    /// @param projectId The ID of the project to pay.
+    /// @param token The token to pay with.
+    /// @param amount The amount to pay, as a fixed point number with the amount of decimals that the terminal's
     /// accounting context specifies.
     /// @param beneficiary The address to receive any platform tokens minted.
     /// @param metadata Additional metadata to include with the payment.
@@ -1366,9 +1368,9 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
 
     /// @notice Fund a project on another terminal by granting a temporary pull allowance for this call only.
     /// @param terminal The recipient terminal.
-    /// @param projectId The ID of the project being funded.
-    /// @param token The token being used.
-    /// @param amount The amount being funded.
+    /// @param projectId The ID of the project to fund.
+    /// @param token The token to use.
+    /// @param amount The amount to fund.
     /// @param metadata Additional metadata to include with the payment.
     function _externalAddToBalance(
         IJBTerminal terminal,
@@ -1400,15 +1402,15 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     }
 
     /// @notice Fulfills a list of cash out hook specifications.
-    /// @param projectId The ID of the project being cashed out from.
-    /// @param beneficiaryReclaimAmount The number of tokens that are being cashed out from the project.
-    /// @param holder The address that holds the tokens being cashed out.
-    /// @param cashOutCount The number of tokens being cashed out.
+    /// @param projectId The ID of the project to cash out from.
+    /// @param beneficiaryReclaimAmount The number of tokens to cash out from the project.
+    /// @param holder The address holding the tokens to cash out.
+    /// @param cashOutCount The number of tokens to cash out.
     /// @param metadata Bytes to send along to the emitted event and cash out hooks as applicable.
-    /// @param ruleset The ruleset the cash out is being made during as a `JBRuleset` struct.
+    /// @param ruleset The ruleset active during this cash out as a `JBRuleset` struct.
     /// @param cashOutTaxRate The cash out tax rate influencing the reclaim amount.
     /// @param beneficiary The address which will receive any terminal tokens that are cashed out.
-    /// @param specifications The hook specifications being fulfilled.
+    /// @param specifications The hook specifications to fulfill.
     /// @return amountEligibleForFees The amount of funds which were allocated to cash out hooks and are eligible for
     /// fees.
     function _fulfillCashOutHookSpecificationsFor(
@@ -1501,13 +1503,13 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     }
 
     /// @notice Fulfills a list of pay hook specifications.
-    /// @param projectId The ID of the project being paid.
+    /// @param projectId The ID of the project to pay.
     /// @param specifications The pay hook specifications to be fulfilled.
     /// @param tokenAmount The amount of tokens that the project was paid.
     /// @param payer The address that sent the payment.
-    /// @param ruleset The ruleset the payment is being accepted during.
+    /// @param ruleset The ruleset active during this payment.
     /// @param beneficiary The address which will receive any tokens that the payment yields.
-    /// @param newlyIssuedTokenCount The amount of tokens that are being issued and sent to the beneificary.
+    /// @param newlyIssuedTokenCount The number of tokens issued and sent to the beneficiary.
     /// @param metadata Bytes to send along to the emitted event and pay hooks as applicable.
     function _fulfillPayHookSpecificationsFor(
         uint256 projectId,
@@ -1586,10 +1588,11 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         }
     }
 
-    /// @notice Pay a project with tokens.
-    /// @param projectId The ID of the project being paid.
-    /// @param token The address of the token which the project is being paid with.
-    /// @param amount The amount of terminal tokens being received, as a fixed point number with the same number of
+    /// @notice Internal implementation of payment logic. Records the payment in the store, mints tokens via the
+    /// controller, and fulfills any pay hook specifications from the data hook.
+    /// @param projectId The ID of the project to pay.
+    /// @param token The address of the token to pay the project with.
+    /// @param amount The amount of tokens to send, as a fixed point number with the same number of
     /// decimals as this terminal. If this terminal's token is the native token, `amount` is ignored and `msg.value` is
     /// used in its place.
     /// @param payer The address making the payment.
@@ -1668,11 +1671,11 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
 
     /// @notice Process a fee of the specified amount from a project.
     /// @param projectId The ID of the project paying the fee.
-    /// @param token The token the fee is being paid in.
+    /// @param token The token the fee is paid in.
     /// @param amount The fee amount, as a fixed point number with 18 decimals.
     /// @param beneficiary The address which will receive any platform tokens minted.
     /// @param feeTerminal The terminal that'll receive the fee.
-    /// @param wasHeld A flag indicating if the fee being processed was being held by this terminal.
+    /// @param wasHeld A flag indicating if the fee to process was held by this terminal.
     function _processFee(
         uint256 projectId,
         address token,
@@ -1727,7 +1730,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     /// @notice Returns held fees to the project who paid them based on the specified amount.
     /// @dev Partial replenishments use the raw floor calculation so repaying a dust amount cannot both credit the
     /// payer project and leave the fee project owed the 1-unit minimum fee.
-    /// @param projectId The project held fees are being returned to.
+    /// @param projectId The project to return held fees to.
     /// @param token The token that the held fees are in.
     /// @param amount The amount to base the calculation on, as a fixed point number with the same number of decimals
     /// as this terminal.
@@ -1808,10 +1811,10 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
 
     /// @notice Sends payouts to a project's payout split group using the specified ruleset.
     /// @param projectId The ID of the project to send the payouts of.
-    /// @param token The token being paid out.
+    /// @param token The token to pay out.
     /// @param amount The number of terminal tokens to pay out, as a fixed point number with same number of decimals as
     /// this terminal.
-    /// @param currency The expected currency of the amount being paid out. Must match the currency of one of the
+    /// @param currency The expected currency of the amount to pay out. Must match the currency of one of the
     /// project's current ruleset's payout limits.
     /// @return amountPaidOut The total amount that was paid out.
     function _sendPayoutsOf(
@@ -1922,10 +1925,10 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
 
     /// @notice Takes a fee into the platform's project (with the `_FEE_BENEFICIARY_PROJECT_ID`).
     /// @param projectId The ID of the project paying the fee.
-    /// @param token The address of the token that the fee is being paid in.
+    /// @param token The address of the token that the fee is paid in.
     /// @param amount The fee's token amount, as a fixed point number with 18 decimals.
     /// @param beneficiary The address to mint the platform's project's tokens for.
-    /// @param shouldHoldFees If fees should be tracked and held instead of being exercised immediately.
+    /// @param shouldHoldFees If fees should be tracked and held instead of processing them immediately.
     /// @return feeAmount The amount of the fee taken.
     function _takeFeeFrom(
         uint256 projectId,
@@ -1978,8 +1981,8 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     /// @notice Transfers tokens.
     /// @param from The address the transfer should originate from.
     /// @param to The address the transfer should go to.
-    /// @param token The token being transfered.
-    /// @param amount The number of tokens being transferred, as a fixed point number with the same number of decimals
+    /// @param token The token to transfer.
+    /// @param amount The number of tokens to transfer, as a fixed point number with the same number of decimals
     /// as this terminal.
     function _transferFrom(address from, address payable to, address token, uint256 amount) internal {
         if (from == address(this)) {
@@ -2008,10 +2011,10 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     /// @dev Incurs the protocol fee unless the caller is a feeless address.
     /// @param projectId The ID of the project to use the surplus allowance of.
     /// @param owner The project's owner.
-    /// @param token The token being paid out from the surplus.
+    /// @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
     /// point number with the same amount of decimals as this terminal.
-    /// @param currency The expected currency of the amount being paid out. Must match the currency of one of the
+    /// @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 beneficiary The address to send the funds to.
     /// @param feeBeneficiary The address to send the tokens resulting from paying the fee.
@@ -2171,7 +2174,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
 
     /// @notice Packages a payment amount with the token's accounting context.
     /// @param projectId The ID of the project the token amount belongs to.
-    /// @param token The token being paid.
+    /// @param token The token to pay with.
     /// @param value The token amount's value.
     /// @return tokenAmount The packaged token amount.
     function _tokenAmountOf(