@bananapus/core-v6 0.0.37 → 0.0.39

package/src/JBFundAccessLimits.sol

@@ -7,8 +7,12 @@ import {IJBFundAccessLimits} from "./interfaces/IJBFundAccessLimits.sol";
 import {JBCurrencyAmount} from "./structs/JBCurrencyAmount.sol";
 import {JBFundAccessLimitGroup} from "./structs/JBFundAccessLimitGroup.sol";
 
-/// @notice Stores and manages terminal fund access limits for each project.
-/// @dev See the `JBFundAccessLimitGroup` struct to learn about payout limits and surplus allowances.
+/// @notice Controls how much a project can withdraw from its terminals each funding cycle. Two types of limits:
+/// **Payout limits** cap how much can be distributed to splits and the project owner. **Surplus allowances** cap how
+/// much the project owner can pull from the surplus (funds above payout limits). Both reset each ruleset cycle.
+/// @dev Limits are denominated in a currency (which may differ from the held token) and resolved at withdrawal time
+/// via `JBPrices`. An empty `fundAccessLimitGroups` array means zero access (not unlimited) — use `type(uint224).max`
+/// for unlimited.
 contract JBFundAccessLimits is JBControlled, IJBFundAccessLimits {
     //*********************************************************************//
     // --------------------------- custom errors ------------------------- //
@@ -61,10 +65,11 @@ contract JBFundAccessLimits is JBControlled, IJBFundAccessLimits {
     // ---------------------- external transactions ---------------------- //
     //*********************************************************************//
 
-    /// @notice Sets limits on the amount of funds a project can access from its terminals during a ruleset.
-    /// @dev Only a project's controller can set its fund access limits.
-    /// @dev Payout limits and surplus allowances must be specified in strictly increasing order (by currency) to
-    /// prevent duplicates.
+    /// @notice Configure how much a project can withdraw from each of its terminals during a ruleset. Payout limits
+    /// cap how much can be distributed to splits/owner; surplus allowances cap how much extra the owner can pull from
+    /// surplus. Both reset each funding cycle.
+    /// @dev Only a project's controller can set fund access limits (called during `queueRulesetsOf`).
+    /// @dev Limits within each group must be sorted by currency in strictly increasing order to prevent duplicates.
     /// @param projectId The ID of the project whose fund access limits are being set.
     /// @param rulesetId The ID of the ruleset that the limits will apply within.
     /// @param fundAccessLimitGroups An array containing payout limits and surplus allowances for each payment terminal.
@@ -152,14 +157,15 @@ contract JBFundAccessLimits is JBControlled, IJBFundAccessLimits {
     // ------------------------- external views -------------------------- //
     //*********************************************************************//
 
-    /// @notice A project's payout limit for a given ruleset, terminal, token, and currency.
-    /// @dev The fixed point return amount will use the same number of decimals as the `terminal`.
+    /// @notice Look up how much a project can distribute (via `sendPayoutsOf`) from a specific terminal and token,
+    /// denominated in a specific currency. Returns 0 if no limit is configured for that currency.
+    /// @dev The fixed point return amount uses the same number of decimals as the terminal.
     /// @param projectId The project's ID.
     /// @param rulesetId The ruleset's ID.
     /// @param terminal The terminal the payout limit applies to.
     /// @param token The token the payout limit applies to.
     /// @param currency The currency the payout limit is denominated in.
-    /// @return payoutLimit The payout limit, as a fixed point number with the same number of decimals as the provided
+    /// @return payoutLimit The payout limit, as a fixed point number with the same number of decimals as the
     /// terminal.
     function payoutLimitOf(
         uint256 projectId,
@@ -195,10 +201,9 @@ contract JBFundAccessLimits is JBControlled, IJBFundAccessLimits {
         }
     }
 
-    /// @notice A project's payout limits for a given ruleset, terminal, and token.
-    /// @dev The total value of `token`s that a project can pay out from the terminal during the ruleset is dictated
-    /// by a list of payout limits. Each payout limit is a fixed-point amount in terms of a currency.
-    /// @dev The fixed point `amount`s returned will use the same number of decimals as the `terminal`.
+    /// @notice Get all payout limits for a project's terminal and token during a ruleset. A project can have multiple
+    /// payout limits denominated in different currencies (e.g. 10,000 USD + 5 ETH). Each is enforced independently.
+    /// @dev The fixed point `amount`s returned use the same number of decimals as the terminal.
     /// @param projectId The project's ID.
     /// @param rulesetId The ruleset's ID.
     /// @param terminal The terminal the payout limits apply to.
@@ -243,15 +248,16 @@ contract JBFundAccessLimits is JBControlled, IJBFundAccessLimits {
         }
     }
 
-    /// @notice A project's surplus allowance for a given ruleset, terminal, token, and currency.
-    /// @dev The fixed point return amount will use the same number of decimals as the `terminal`.
+    /// @notice Look up how much a project's owner can withdraw from the surplus (via `useAllowanceOf`) from a specific
+    /// terminal and token, denominated in a specific currency. Returns 0 if no allowance is configured.
+    /// @dev The fixed point return amount uses the same number of decimals as the terminal.
     /// @param projectId The project's ID.
     /// @param rulesetId The ruleset's ID.
     /// @param terminal The terminal the surplus allowance applies to.
     /// @param token The token the surplus allowance applies to.
     /// @param currency The currency that the surplus allowance is denominated in.
     /// @return surplusAllowance The surplus allowance, as a fixed point number with the same number of decimals as the
-    /// provided terminal.
+    /// terminal.
     function surplusAllowanceOf(
         uint256 projectId,
         uint256 rulesetId,
@@ -287,11 +293,9 @@ contract JBFundAccessLimits is JBControlled, IJBFundAccessLimits {
         }
     }
 
-    /// @notice A project's surplus allowances for a given ruleset, terminal, and token.
-    /// @dev The total value of `token`s that a project can pay out from its surplus in a terminal during the ruleset
-    /// is dictated by a list of surplus allowances. Each surplus allowance is a fixed-point amount in terms of a
-    /// currency.
-    /// @dev The fixed point `amount`s returned will use the same number of decimals as the `terminal`.
+    /// @notice Get all surplus allowances for a project's terminal and token during a ruleset. Like payout limits, a
+    /// project can have multiple surplus allowances in different currencies, each enforced independently.
+    /// @dev The fixed point `amount`s returned use the same number of decimals as the terminal.
     /// @param projectId The project's ID.
     /// @param rulesetId The ruleset's ID.
     /// @param terminal The terminal the surplus allowances apply to.

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;
@@ -83,6 +88,9 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     // ------------------------ internal constants ----------------------- //
     //*********************************************************************//
 
+    /// @notice Denominator for forward-calculating this terminal's fee from a pre-fee amount.
+    uint256 internal constant _FEE_AMOUNT_FROM_DENOMINATOR = JBConstants.MAX_FEE / FEE;
+
     /// @notice Project ID #1 receives fees. It should be the first project launched during the deployment process.
     uint256 internal constant _FEE_BENEFICIARY_PROJECT_ID = 1;
 
@@ -182,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(
@@ -216,8 +224,9 @@ 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.
@@ -248,10 +257,9 @@ 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.
+    /// @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 whose tokens are being cashed out.
     /// @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
@@ -330,15 +338,18 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             // This payout is eligible for a fee since the funds are leaving this contract and the split hook isn't a
             // feeless address.
             if (!_isFeeless(address(split.hook))) {
-                netPayoutAmount -= JBFees.feeAmountFrom({amountBeforeFee: amount, feePercent: FEE});
+                unchecked {
+                    netPayoutAmount -= _feeAmountFrom(amount);
+                }
             }
 
             // Create the context to send to the split hook.
             JBSplitHookContext memory context = JBSplitHookContext({
                 token: token,
                 amount: netPayoutAmount,
-                decimals: STORE.accountingContextOf({terminal: address(this), projectId: projectId, token: token})
-                .decimals,
+                decimals: STORE.accountingContextOf({
+                    terminal: address(this), projectId: projectId, token: token
+                }).decimals,
                 projectId: projectId,
                 groupId: uint256(uint160(token)),
                 split: split
@@ -370,7 +381,9 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             // This payout is eligible for a fee if the funds are leaving this contract and the receiving terminal isn't
             // a feeless address.
             if (terminal != this && !_isFeeless(address(terminal))) {
-                netPayoutAmount -= JBFees.feeAmountFrom({amountBeforeFee: amount, feePercent: FEE});
+                unchecked {
+                    netPayoutAmount -= _feeAmountFrom(amount);
+                }
             }
 
             // Track the fee-free payout amount. During cashout at zero tax rate, fees apply
@@ -430,7 +443,9 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             // This payout is eligible for a fee since the funds are leaving this contract and the recipient isn't a
             // feeless address.
             if (!_isFeeless(recipient)) {
-                netPayoutAmount -= JBFees.feeAmountFrom({amountBeforeFee: amount, feePercent: FEE});
+                unchecked {
+                    netPayoutAmount -= _feeAmountFrom(amount);
+                }
             }
 
             // If there's a beneficiary, send the funds directly to the beneficiary. Otherwise send to the
@@ -553,7 +568,8 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         }
     }
 
-    /// @notice Pay a project with tokens.
+    /// @notice Pay a project with tokens. The project's current ruleset determines how many project tokens the
+    /// beneficiary receives in return.
     /// @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
     /// decimals as this terminal. If this terminal's token is native, this is ignored and `msg.value` is used in its
@@ -612,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.
@@ -647,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:
@@ -664,7 +675,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             _processFee({
                 projectId: projectId,
                 token: token,
-                amount: JBFees.feeAmountFrom({amountBeforeFee: heldFee.amount, feePercent: FEE}),
+                amount: _feeAmountFrom(heldFee.amount),
                 beneficiary: heldFee.beneficiary,
                 feeTerminal: feeTerminal,
                 wasHeld: true
@@ -684,15 +695,12 @@ 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 amount The total number of terminal tokens to send, as a fixed point number with same number of decimals
@@ -720,10 +728,10 @@ 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 amount The amount of terminal tokens to use from the project's current surplus allowance, as a fixed
@@ -777,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.
@@ -794,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.
@@ -827,9 +835,10 @@ 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.
+    /// @notice Returns the fees currently being 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 that is holding fees.
     /// @param token The token that the fees are held in.
     /// @param count The maximum number of held fees to return.
@@ -868,7 +877,8 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         }
     }
 
-    /// @notice Simulates cashing out project tokens from this terminal without modifying state.
+    /// @notice Simulates a cash out without modifying state — use this to preview how many tokens a holder would
+    /// reclaim.
     /// @param holder The address whose tokens are being cashed out.
     /// @param projectId The ID of the project whose tokens are being cashed out.
     /// @param cashOutCount The number of project tokens to cash out.
@@ -909,7 +919,9 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             });
     }
 
-    /// @notice Simulates paying a project through this terminal without modifying state.
+    /// @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 being paid.
     /// @param token The token being paid in.
     /// @param amount The amount of tokens being paid.
@@ -1180,16 +1192,22 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
                 if (cashOutTaxRate != 0) {
                     // Non-zero tax: fees apply to the full reclaim amount.
                     amountEligibleForFees += reclaimAmount;
-                    reclaimAmount -= JBFees.feeAmountFrom({amountBeforeFee: reclaimAmount, feePercent: FEE});
+                    unchecked {
+                        reclaimAmount -= _feeAmountFrom(reclaimAmount);
+                    }
                 } else {
                     // Zero tax: fees apply only up to the fee-free surplus (round-trip prevention).
                     uint256 feeFreeSurplus = _feeFreeSurplusOf[projectId][tokenToReclaim];
                     if (feeFreeSurplus != 0) {
                         uint256 feeableAmount = reclaimAmount < feeFreeSurplus ? reclaimAmount : feeFreeSurplus;
                         // slither-disable-next-line reentrancy-no-eth,reentrancy-eth,reentrancy-benign
-                        _feeFreeSurplusOf[projectId][tokenToReclaim] = feeFreeSurplus - feeableAmount;
+                        unchecked {
+                            _feeFreeSurplusOf[projectId][tokenToReclaim] = feeFreeSurplus - feeableAmount;
+                        }
                         amountEligibleForFees += feeableAmount;
-                        reclaimAmount -= JBFees.feeAmountFrom({amountBeforeFee: feeableAmount, feePercent: FEE});
+                        unchecked {
+                            reclaimAmount -= _feeAmountFrom(feeableAmount);
+                        }
                     }
                 }
             }
@@ -1437,9 +1455,8 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             }
 
             // Get the fee for the specified amount.
-            uint256 specificationAmountFee = _isFeeless(address(specification.hook))
-                ? 0
-                : JBFees.feeAmountFrom({amountBeforeFee: specification.amount, feePercent: FEE});
+            uint256 specificationAmountFee =
+                _isFeeless(address(specification.hook)) ? 0 : _feeAmountFrom(specification.amount);
 
             // Add the specification's amount to the amount eligible for fees.
             if (specificationAmountFee != 0) {
@@ -1571,7 +1588,8 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         }
     }
 
-    /// @notice Pay a project with tokens.
+    /// @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 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
@@ -1615,12 +1633,12 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             // slither-disable-next-line reentrancy-events
             newlyIssuedTokenCount = _controllerOf(projectId)
                 .mintTokensOf({
-                    projectId: projectId,
-                    tokenCount: tokenCount,
-                    beneficiary: beneficiary,
-                    memo: "",
-                    useReservedPercent: true
-                });
+                projectId: projectId,
+                tokenCount: tokenCount,
+                beneficiary: beneficiary,
+                memo: "",
+                useReservedPercent: true
+            });
         }
 
         emit Pay({
@@ -1710,8 +1728,8 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     }
 
     /// @notice Returns held fees to the project who paid them based on the specified amount.
-    /// @dev Fee rounding during partial replenishment can zero out dust-level fee entries (< 40 wei at 2.5% fee).
-    /// This is accepted behavior — dust fees are economically insignificant.
+    /// @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 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
@@ -1747,7 +1765,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
                 break;
             } else {
                 // Notice here we take `feeAmountFrom` on the stored `.amount`.
-                uint256 feeAmount = JBFees.feeAmountFrom({amountBeforeFee: heldFee.amount, feePercent: FEE});
+                uint256 feeAmount = _feeAmountFrom(heldFee.amount);
 
                 // Keep a reference to the amount from which the fee was taken.
                 uint256 amountPaidOut = heldFee.amount - feeAmount;
@@ -1761,8 +1779,9 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
                     // Move the start index forward to the held fee after the current one.
                     newStartIndex = startIndex + i + 1;
                 } else {
-                    // And here we overwrite with `feeAmountResultingIn` the `leftoverAmount`
-                    feeAmount = JBFees.feeAmountResultingIn({amountAfterFee: leftoverAmount, feePercent: FEE});
+                    // Use the floor variant here. The minimum 1-unit fee applies when a fee is created, not while
+                    // splitting an already-held fee entry across repayments.
+                    feeAmount = JBFees.feeAmountResultingInFloorForFee25(leftoverAmount);
 
                     // Get fee from `leftoverAmount`.
                     unchecked {
@@ -1817,10 +1836,6 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         (ruleset, amountPaidOut) =
             STORE.recordPayoutFor({projectId: projectId, token: token, amount: amount, currency: currency});
 
-        // Cap fee-free surplus at remaining balance. Non-fee-free funds leave first.
-        // slither-disable-next-line reentrancy-no-eth,reentrancy-eth,reentrancy-benign
-        _capFeeFreeSurplus({projectId: projectId, token: token});
-
         // 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.
@@ -1849,17 +1864,20 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         // Send any leftover funds to the project owner and update the fee tracking accordingly.
         if (leftoverPayoutAmount != 0) {
             // Keep a reference to the fee for the leftover payout amount.
-            uint256 fee = _isFeeless(projectOwner)
-                ? 0
-                : JBFees.feeAmountFrom({amountBeforeFee: leftoverPayoutAmount, feePercent: FEE});
+            uint256 fee = _isFeeless(projectOwner) ? 0 : _feeAmountFrom(leftoverPayoutAmount);
+
+            uint256 netLeftoverPayoutAmount;
+            unchecked {
+                netLeftoverPayoutAmount = leftoverPayoutAmount - fee;
+            }
 
             // Failed owner transfer consumes the payout limit by design. Same pattern as split payouts:
             // the try-catch prevents revert, failed amount is returned to project balance, and the owner can retry
             // via addToBalanceOf or in the next cycle.
-            try this.executeTransferTo({addr: projectOwner, token: token, amount: leftoverPayoutAmount - fee}) {
+            try this.executeTransferTo({addr: projectOwner, token: token, amount: netLeftoverPayoutAmount}) {
                 if (fee > 0) {
                     amountEligibleForFees += leftoverPayoutAmount;
-                    leftoverPayoutAmount -= fee;
+                    leftoverPayoutAmount = netLeftoverPayoutAmount;
                 }
             } catch (bytes memory reason) {
                 // slither-disable-next-line reentrancy-events
@@ -1867,7 +1885,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
                     projectId: projectId,
                     addr: projectOwner,
                     token: token,
-                    amount: leftoverPayoutAmount - fee,
+                    amount: netLeftoverPayoutAmount,
                     fee: fee,
                     reason: reason,
                     caller: sender
@@ -1878,6 +1896,11 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             }
         }
 
+        // Cap fee-free surplus at remaining balance. Non-fee-free funds leave first.
+        // Placed after all payouts settle so the cap reflects post-payout state.
+        // slither-disable-next-line reentrancy-no-eth,reentrancy-eth,reentrancy-benign
+        _capFeeFreeSurplus({projectId: projectId, token: token});
+
         // Take the fee.
         uint256 feeTaken = _takeFeeFrom({
             projectId: projectId,
@@ -1918,7 +1941,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         returns (uint256 feeAmount)
     {
         // Get a reference to the fee amount.
-        feeAmount = JBFees.feeAmountFrom({amountBeforeFee: amount, feePercent: FEE});
+        feeAmount = _feeAmountFrom(amount);
 
         if (shouldHoldFees) {
             // Store the held fee.
@@ -2170,4 +2193,18 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         tokenAmount =
             JBTokenAmount({token: token, decimals: context.decimals, currency: context.currency, value: value});
     }
+
+    //*********************************************************************//
+    // -------------------------- private helpers ------------------------ //
+    //*********************************************************************//
+
+    /// @notice The terminal fee charged from a pre-fee `amount`.
+    /// @dev Returns at least 1 for nonzero feeable amounts so dust payouts cannot bypass protocol fees.
+    /// @param amount The amount before the fee is applied.
+    /// @return feeAmount The fee amount.
+    function _feeAmountFrom(uint256 amount) private pure returns (uint256 feeAmount) {
+        feeAmount = amount / _FEE_AMOUNT_FROM_DENOMINATOR;
+
+        return feeAmount == 0 && amount != 0 ? 1 : feeAmount;
+    }
 }