@bananapus/core-v6 0.0.16 → 0.0.17

package/src/JBDeadline.sol

@@ -11,6 +11,9 @@ import {JBRuleset} from "./structs/JBRuleset.sol";
 /// seconds before the current ruleset ends. In other words, rulesets must be queued before the deadline to take effect.
 /// @dev Project rulesets are stored in a queue. Rulesets take effect after the previous ruleset in the queue ends, and
 /// only if they are approved by the previous ruleset's approval hook.
+/// @dev If `DURATION` is set longer than the ruleset's cycle duration, no queued ruleset can ever satisfy the deadline
+/// and the current ruleset will effectively be locked in perpetuity. Choose a `DURATION` shorter than the shortest
+/// cycle it will govern.
 contract JBDeadline is IJBRulesetApprovalHook {
     //*********************************************************************//
     // ---------------- public immutable stored properties --------------- //

package/src/JBDirectory.sol

@@ -185,7 +185,8 @@ contract JBDirectory is JBPermissioned, Ownable, IJBDirectory {
             revert JBDirectory_TokenNotAccepted(projectId, token, terminal);
         }
 
-        // If the terminal hasn't already been added to the project, add it.
+        // Implicit terminal addition is by design. A primary terminal must be in the terminals list;
+        // implicit addition avoids requiring a separate addTerminalsOf call.
         _addTerminalIfNeeded({projectId: projectId, terminal: terminal});
 
         // Store the terminal as the project's primary terminal for the token.

package/src/JBMultiTerminal.sol

@@ -136,6 +136,18 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     /// @custom:param projectId The ID of the project to get a list of accepted tokens for.
     mapping(uint256 projectId => JBAccountingContext[]) internal _accountingContextsOf;
 
+    /// @notice The cumulative amount of fee-free intra-terminal payouts a project has received for a given token.
+    /// @dev Incremented each time a fee-free payout lands (same terminal, no fee charged). During cashout with
+    /// `cashOutTaxRate == 0`, fees are applied only up to this amount, then decremented. This prevents a round-trip
+    /// fee bypass (intra-terminal payout → zero-tax cashout) while scoping the fee precisely to the fee-free inflow
+    /// — legitimate cashouts beyond this amount remain fee-free.
+    /// @dev WARNING: This accumulator persists across rulesets and cannot be cleared. Once a fee-free payout
+    /// increments it, the balance remains until consumed by a zero-tax cashout. There is no admin function to reset
+    /// it. Projects switching from zero-tax to non-zero-tax rulesets will carry forward any unconsumed balance.
+    /// @custom:param projectId The ID of the project that received the payout.
+    /// @custom:param token The token that was received.
+    mapping(uint256 projectId => mapping(address token => uint256)) internal _feeFreeSurplusOf;
+
     /// @notice Fees that are being 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.
@@ -416,12 +428,21 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
                 revert JBMultiTerminal_RecipientProjectTerminalNotFound(split.projectId, token);
             }
 
+            // Fees apply to fund egress, not intra-terminal accounting. When both projects share this terminal,
+            // funds stay within the contract (addToBalance or pay) so no fee is charged. This is intentional:
+            // the fee model taxes value leaving the protocol ecosystem, not internal rebalancing.
             // This payout is eligible for a fee if the funds are leaving this contract and the receiving terminal isn't
-            // a feelss address.
+            // a feeless address.
             if (terminal != this && !_isFeeless(address(terminal))) {
                 netPayoutAmount -= JBFees.feeAmountFrom({amountBeforeFee: amount, feePercent: FEE});
             }
 
+            // Track the fee-free payout amount. During cashout at zero tax rate, fees apply
+            // only up to this accumulated amount, preventing round-trip fee bypass.
+            if (terminal == this) {
+                _feeFreeSurplusOf[split.projectId][token] += netPayoutAmount;
+            }
+
             // Send the `projectId` in the metadata as a referral.
             bytes memory metadata = bytes(abi.encodePacked(projectId));
 
@@ -541,6 +562,8 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             revert JBMultiTerminal_TerminalTokensIncompatible({projectId: projectId, token: token, terminal: to});
         }
 
+        // Terminal migration intentionally does not transfer held fees. Held fees belong to the
+        // fee beneficiary (project #1), not the migrating project. They unlock after 28 days regardless of terminal.
         // Record the migration in the store.
         // slither-disable-next-line reentrancy-events
         balance = STORE.recordTerminalMigration({projectId: projectId, token: token});
@@ -625,6 +648,8 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     }
 
     /// @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.
     /// @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.
@@ -1049,6 +1074,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
                 accountingContext: accountingContext,
                 balanceAccountingContexts: balanceAccountingContexts,
                 cashOutCount: cashOutCount,
+                beneficiaryIsFeeless: _isFeeless(beneficiary),
                 metadata: metadata
             });
         }
@@ -1064,12 +1090,22 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
 
         // Send the reclaimed funds to the beneficiary.
         if (reclaimAmount != 0) {
-            // Determine if a fee should be taken. Fees are not taked if the cash out tax rate is zero,
-            // if the beneficiary is feeless, or if the fee beneficiary doesn't accept the given token.
-            if (!_isFeeless(beneficiary) && cashOutTaxRate != 0) {
-                amountEligibleForFees += reclaimAmount;
-                // Subtract the fee for the reclaimed amount.
-                reclaimAmount -= JBFees.feeAmountFrom({amountBeforeFee: reclaimAmount, feePercent: FEE});
+            // Determine if a fee should be taken. Fees are not taken if the beneficiary is feeless.
+            if (!_isFeeless(beneficiary)) {
+                if (cashOutTaxRate != 0) {
+                    // Non-zero tax: fees apply to the full reclaim amount.
+                    amountEligibleForFees += reclaimAmount;
+                    reclaimAmount -= JBFees.feeAmountFrom({amountBeforeFee: reclaimAmount, feePercent: FEE});
+                } 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;
+                        _feeFreeSurplusOf[projectId][tokenToReclaim] = feeFreeSurplus - feeableAmount;
+                        amountEligibleForFees += feeableAmount;
+                        reclaimAmount -= JBFees.feeAmountFrom({amountBeforeFee: feeableAmount, feePercent: FEE});
+                    }
+                }
             }
 
             // Subtract the fee from the reclaim amount.
@@ -1623,7 +1659,10 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         internal
         returns (uint256)
     {
-        // Attempt to distribute this split.
+        // Failed split payouts consume the payout limit by design. The try-catch prevents a single
+        // split from DoS-ing the entire payout. Failed splits' amounts are returned to the project balance via
+        // `_recordAddedBalanceFor`. Payout limit consumption is correct because the project authorized the
+        // distribution.
         // slither-disable-next-line reentrancy-events
         try this.executePayout({
             split: split, projectId: projectId, token: token, amount: amount, originalMessageSender: _msgSender()
@@ -1697,7 +1736,9 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
                 ? 0
                 : JBFees.feeAmountFrom({amountBeforeFee: leftoverPayoutAmount, feePercent: FEE});
 
-            // Transfer the amount to the project owner.
+            // 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}) {
                 if (fee > 0) {
                     amountEligibleForFees += leftoverPayoutAmount;

package/src/JBPermissions.sol

@@ -154,6 +154,8 @@ contract JBPermissions is ERC2771Context, IJBPermissions {
         uint256 operatorAccountWildcardProjectPermissions =
             includeWildcardProjectId ? permissionsOf[operator][account][WILDCARD_PROJECT_ID] : 0;
 
+        // Returns true for empty permission arrays by design (vacuous truth). An empty set of
+        // required permissions is trivially satisfied. Callers should validate non-empty permission arrays if needed.
         for (uint256 i; i < permissionIds.length; i++) {
             // Set the permission being iterated on.
             uint256 permissionId = permissionIds[i];

package/src/JBPrices.sol

@@ -15,8 +15,10 @@ import {IJBProjects} from "./interfaces/IJBProjects.sol";
 
 /// @notice Manages and normalizes price feeds. Price feeds are contracts which return the "pricing currency" cost of 1
 /// "unit currency".
-/// @dev Price feeds are immutable once set and cannot be replaced or removed. If a price feed needs to be changed,
-/// a new JBPrices contract must be deployed and projects must migrate to use it.
+/// @dev Price feeds are immutable once set and cannot be replaced or removed. This prevents oracle manipulation via
+/// admin-key attacks, but means a misconfigured or failing feed will cause operations using that currency pair to
+/// revert (DoS, not fund loss). Select feeds carefully — recovery requires deploying a new JBPrices contract and
+/// migrating projects.
 contract JBPrices is JBControlled, JBPermissioned, ERC2771Context, Ownable, IJBPrices {
     //*********************************************************************//
     // --------------------------- custom errors ------------------------- //
@@ -134,6 +136,10 @@ contract JBPrices is JBControlled, JBPermissioned, ERC2771Context, Ownable, IJBP
                     : priceFeedFor[projectId][unitCurrency][pricingCurrency]);
         }
 
+        // Price feed immutability is by design to prevent admin-key attacks on price oracles.
+        // If a feed fails, operations using that currency pair revert (DoS but not fund loss). Projects can use
+        // alternative currency pairs. A default feed for a currency pair prevents per-project overrides to ensure
+        // price consistency; projects should use unused currency IDs for custom pricing.
         // Store the feed.
         priceFeedFor[projectId][pricingCurrency][unitCurrency] = feed;
 

package/src/JBRulesets.sol

@@ -353,6 +353,9 @@ contract JBRulesets is JBControlled, IJBRulesets {
 
     /// @notice The ruleset that is currently active for the specified project.
     /// @dev If a current ruleset of the project is not found, returns an empty ruleset with all properties set to 0.
+    /// @dev The first cycle returns the stored ruleset directly (cycleNumber=1, original weight). Subsequent cycles
+    /// simulate cycling with weight decay via `_simulateCycledRulesetBasedOn`. Payout limits reset each cycle because
+    /// the terminal store keys usage by rulesetId, and each cycle produces a new simulated rulesetId.
     /// @param projectId The ID of the project to get the current ruleset of.
     /// @return ruleset The project's current ruleset.
     function currentOf(uint256 projectId) external view override returns (JBRuleset memory ruleset) {

package/src/JBSplits.sol

@@ -77,8 +77,9 @@ contract JBSplits is JBControlled, IJBSplits {
 
     /// @notice Sets a project's split groups.
     /// @dev Only a project's controller can set its splits, unless the first 160 bits of the group's ID match
-    /// `msg.sender`, in which case the caller can set its own splits. The remaining upper 96 bits are free for the
-    /// caller to use as sub-categorization.
+    /// `msg.sender` AND the upper 96 bits are non-zero, in which case the caller can set its own splits.
+    /// GroupIds with zero upper 96 bits (i.e. bare addresses) are reserved for protocol use (e.g. terminal
+    /// payout groups keyed by token address) and always require controller authorization.
     /// @dev The new split groups must include any currently set splits that are locked.
     /// @param projectId The ID of the project to set the split groups of.
     /// @param rulesetId The ID of the ruleset the split groups should be active in. Send
@@ -101,9 +102,12 @@ contract JBSplits is JBControlled, IJBSplits {
             // Get a reference to the grouped split being iterated on.
             JBSplitGroup memory splitGroup = splitGroups[i];
 
-            // Allow contracts to set splits in their own namespace (first 160 bits of groupId == msg.sender).
-            // Otherwise, require controller (checked once).
-            if (address(uint160(splitGroup.groupId)) != msg.sender && !controllerChecked) {
+            // Self-auth: lower 160 bits must match msg.sender AND upper 96 bits must be non-zero.
+            // GroupIds with zero upper bits are reserved for protocol use (e.g. terminal payout groups)
+            // and always require controller authorization to prevent token contracts from hijacking payouts.
+            bool isSelfManaged = splitGroup.groupId >> 160 != 0 && address(uint160(splitGroup.groupId)) == msg.sender;
+
+            if (!isSelfManaged && !controllerChecked) {
                 _onlyControllerOf(projectId);
                 controllerChecked = true;
             }

package/src/JBTerminalStore.sol

@@ -156,6 +156,8 @@ contract JBTerminalStore is IJBTerminalStore {
     /// @param accountingContext The accounting context of the token being reclaimed by the cash out.
     /// @param balanceAccountingContexts The accounting contexts of the tokens whose balances should contribute to the
     /// surplus being reclaimed from.
+    /// @param beneficiaryIsFeeless Whether the cash out's beneficiary is a feeless address. Passed through to data
+    /// hooks so they can skip their own fees when value stays in the protocol (e.g. project-to-project routing).
     /// @param metadata Bytes to send to the data hook, if the project's current ruleset specifies one.
     /// @return ruleset The ruleset during the cash out was made during, as a `JBRuleset` struct. This ruleset will
     /// have a cash out tax rate provided by the cash out hook if applicable.
@@ -170,6 +172,7 @@ contract JBTerminalStore is IJBTerminalStore {
         uint256 cashOutCount,
         JBAccountingContext calldata accountingContext,
         JBAccountingContext[] calldata balanceAccountingContexts,
+        bool beneficiaryIsFeeless,
         bytes memory metadata
     )
         external
@@ -184,10 +187,9 @@ contract JBTerminalStore is IJBTerminalStore {
         // Get a reference to the project's current ruleset.
         ruleset = RULESETS.currentOf(projectId);
 
-        // Get the current surplus amount.
-        // Use the local surplus if the ruleset specifies that it should be used. Otherwise, use the project's total
-        // surplus across all of its terminals.
-        uint256 currentSurplus = ruleset.useTotalSurplusForCashOuts()
+        // Store the current surplus in `reclaimAmount` temporarily to avoid allocating a separate local variable
+        // (saves one stack slot, which is needed to fit the 7th parameter without hitting stack-too-deep).
+        reclaimAmount = ruleset.useTotalSurplusForCashOuts()
             ? JBSurplus.currentSurplusOf({
                 projectId: projectId,
                 terminals: DIRECTORY.terminalsOf(projectId),
@@ -204,54 +206,59 @@ contract JBTerminalStore is IJBTerminalStore {
                 targetCurrency: accountingContext.currency
             });
 
-        // Get the total number of outstanding project tokens.
-        uint256 totalSupply =
-            IJBController(address(DIRECTORY.controllerOf(projectId))).totalTokenSupplyWithReservedTokensOf(projectId);
-
-        // Can't cash out more tokens than are in the supply.
-        if (cashOutCount > totalSupply) revert JBTerminalStore_InsufficientTokens(cashOutCount, totalSupply);
-
-        // SECURITY NOTE: The data hook has absolute control over cash-out economics.
-        // It can set totalSupply, cashOutCount, and cashOutTaxRate to arbitrary values,
-        // completely overriding the terminal's bonding curve math. For example, setting
-        // totalSupply = surplus makes reclaimAmount = cashOutCount, bypassing the curve.
-        // Project owners MUST audit their data hooks with the same rigor as the terminal.
-
-        // If the ruleset has a data hook which is enabled for cash outs, use it to derive a claim amount and memo.
-        if (ruleset.useDataHookForCashOut() && ruleset.dataHook() != address(0)) {
-            // Create the cash out context that'll be sent to the data hook.
-            JBBeforeCashOutRecordedContext memory context = JBBeforeCashOutRecordedContext({
-                terminal: msg.sender,
-                holder: holder,
-                projectId: projectId,
-                rulesetId: ruleset.id,
-                cashOutCount: cashOutCount,
-                totalSupply: totalSupply,
-                surplus: JBTokenAmount({
+        // Scoped to keep `totalSupply` and `context` off the outer stack.
+        {
+            // Get the total number of outstanding project tokens.
+            uint256 totalSupply = IJBController(address(DIRECTORY.controllerOf(projectId)))
+                .totalTokenSupplyWithReservedTokensOf(projectId);
+
+            // Can't cash out more tokens than are in the supply.
+            if (cashOutCount > totalSupply) revert JBTerminalStore_InsufficientTokens(cashOutCount, totalSupply);
+
+            // SECURITY NOTE: The data hook has absolute control over cash-out economics.
+            // It can set totalSupply, cashOutCount, and cashOutTaxRate to arbitrary values,
+            // completely overriding the terminal's bonding curve math. For example, setting
+            // totalSupply = surplus makes reclaimAmount = cashOutCount, bypassing the curve.
+            // Project owners MUST audit their data hooks with the same rigor as the terminal.
+
+            // If the ruleset has a data hook which is enabled for cash outs, use it to derive a claim amount and memo.
+            if (ruleset.useDataHookForCashOut() && ruleset.dataHook() != address(0)) {
+                // Build the cash out context field-by-field to avoid stack-too-deep
+                // (the struct has 11 fields — a struct literal would require all values on the stack at once).
+                JBBeforeCashOutRecordedContext memory context;
+                context.terminal = msg.sender;
+                context.holder = holder;
+                context.projectId = projectId;
+                context.rulesetId = ruleset.id;
+                context.cashOutCount = cashOutCount;
+                context.totalSupply = totalSupply;
+                context.surplus = JBTokenAmount({
                     token: accountingContext.token,
-                    value: currentSurplus,
+                    value: reclaimAmount, // reclaimAmount temporarily holds the current surplus.
                     decimals: accountingContext.decimals,
                     currency: accountingContext.currency
-                }),
-                useTotalSurplus: ruleset.useTotalSurplusForCashOuts(),
-                cashOutTaxRate: ruleset.cashOutTaxRate(),
-                metadata: metadata
-            });
+                });
+                context.useTotalSurplus = ruleset.useTotalSurplusForCashOuts();
+                context.cashOutTaxRate = ruleset.cashOutTaxRate();
+                context.beneficiaryIsFeeless = beneficiaryIsFeeless;
+                context.metadata = metadata;
 
-            (cashOutTaxRate, cashOutCount, totalSupply, hookSpecifications) =
-                IJBRulesetDataHook(ruleset.dataHook()).beforeCashOutRecordedWith(context);
-        } else {
-            cashOutTaxRate = ruleset.cashOutTaxRate();
-        }
+                (cashOutTaxRate, cashOutCount, totalSupply, hookSpecifications) =
+                    IJBRulesetDataHook(ruleset.dataHook()).beforeCashOutRecordedWith(context);
+            } else {
+                cashOutTaxRate = ruleset.cashOutTaxRate();
+            }
 
-        if (currentSurplus != 0) {
-            // Calculate reclaim amount using the current surplus amount.
-            reclaimAmount = JBCashOuts.cashOutFrom({
-                surplus: currentSurplus,
-                cashOutCount: cashOutCount,
-                totalSupply: totalSupply,
-                cashOutTaxRate: cashOutTaxRate
-            });
+            // Calculate the reclaim amount. `reclaimAmount` currently holds the surplus — overwrite it with the
+            // result.
+            if (reclaimAmount != 0) {
+                reclaimAmount = JBCashOuts.cashOutFrom({
+                    surplus: reclaimAmount,
+                    cashOutCount: cashOutCount,
+                    totalSupply: totalSupply,
+                    cashOutTaxRate: cashOutTaxRate
+                });
+            }
         }
 
         // Keep a reference to the amount that should be added to the project's balance.

package/src/JBTokens.sol

@@ -275,6 +275,9 @@ contract JBTokens is JBControlled, IJBTokens {
 
     /// @notice Set a project's token if not already set.
     /// @dev Only a project's controller can set its token.
+    /// @dev If the provided ERC-20 has a pre-existing supply (minted outside this contract), that supply will be
+    /// included in `totalSupplyOf` and will dilute cash-out calculations for all token holders. Project owners are
+    /// responsible for ensuring the token's supply is appropriate before calling this function.
     /// @param projectId The ID of the project to set the token of.
     /// @param token The new token's address.
     function setTokenFor(uint256 projectId, IJBToken token) external override onlyControllerOf(projectId) {

package/src/interfaces/IJBTerminalStore.sol

@@ -145,6 +145,8 @@ interface IJBTerminalStore {
     /// @param cashOutCount The number of project tokens being cashed out.
     /// @param accountingContext The accounting context of the token being reclaimed.
     /// @param balanceAccountingContexts The accounting contexts to include in the balance calculation.
+    /// @param beneficiaryIsFeeless Whether the cash out's beneficiary is a feeless address. Passed through to data
+    /// hooks so they can skip their own fees when value stays in the protocol (e.g. project-to-project routing).
     /// @param metadata Extra data to pass along to the data hook.
     /// @return ruleset The project's current ruleset.
     /// @return reclaimAmount The amount reclaimed.
@@ -156,6 +158,7 @@ interface IJBTerminalStore {
         uint256 cashOutCount,
         JBAccountingContext calldata accountingContext,
         JBAccountingContext[] calldata balanceAccountingContexts,
+        bool beneficiaryIsFeeless,
         bytes calldata metadata
     )
         external

package/src/libraries/JBFees.sol

@@ -19,6 +19,8 @@ library JBFees {
 
     /// @notice Returns the fee that would be taken from `amountBeforeFee`.
     /// @dev Use this to forward-calculate the fee from a known pre-fee amount.
+    /// @dev Fee rounding error is bounded by N-1 wei (N = number of splits). Economically
+    /// insignificant. Rounds down (mulDiv floors), so the fee beneficiary may receive up to 1 wei less per split.
     /// @param amountBeforeFee The amount before the fee is applied, as a fixed point number.
     /// @param feePercent The fee percent, out of `JBConstants.MAX_FEE`.
     /// @return The fee amount, as a fixed point number with the same number of decimals as the provided `amount`.

package/src/libraries/JBMetadataResolver.sol

@@ -60,6 +60,9 @@ library JBMetadataResolver {
         pure
         returns (bytes memory newMetadata)
     {
+        // Validate data padding upfront so that the fast path below cannot bypass the check.
+        if (dataToAdd.length < 32) revert JBMetadataResolver_DataNotPadded();
+
         // Empty original metadata and maybe something in the first 32 bytes: create new metadata
         if (originalMetadata.length <= RESERVED_SIZE) {
             // forge-lint: disable-next-line(unsafe-typecast)
@@ -69,9 +72,6 @@ library JBMetadataResolver {
         // There is something in the table offset, but not a valid entry - avoid overwriting
         if (originalMetadata.length < RESERVED_SIZE + ID_SIZE + 1) revert JBMetadataResolver_MetadataTooShort();
 
-        // Make sure the data is padded to 32 bytes.
-        if (dataToAdd.length < 32) revert JBMetadataResolver_DataNotPadded();
-
         // Get the first data offset - upcast to avoid overflow (same for other offset)...
         uint256 firstOffset = uint8(originalMetadata[RESERVED_SIZE + ID_SIZE]);
 
@@ -103,7 +103,10 @@ library JBMetadataResolver {
                 if (i + TOTAL_ID_SIZE >= firstOffset * WORD_SIZE) {
                     // Increment every offset by 1 (as the table now takes one more word)
                     for (uint256 j = RESERVED_SIZE + ID_SIZE; j < lastOffsetIndex + 1; j += TOTAL_ID_SIZE) {
-                        newMetadata[j] = bytes1(uint8(originalMetadata[j]) + 1);
+                        uint256 incremented = uint256(uint8(originalMetadata[j])) + 1;
+                        if (incremented > 255) revert JBMetadataResolver_MetadataTooLong();
+                        // forge-lint: disable-next-line(unsafe-typecast)
+                        newMetadata[j] = bytes1(uint8(incremented));
                     }
 
                     // Increment the last offset so the new offset will be properly set too
@@ -123,6 +126,10 @@ library JBMetadataResolver {
         newMetadata = abi.encodePacked(newMetadata, idToAdd, bytes1(uint8(newOffset)));
 
         // Pad as needed - inlined for gas saving
+        // The length inflation to the next 32-byte boundary does NOT read uninitialized memory.
+        // abi.encodePacked always advances the free memory pointer to a 32-byte-aligned position, so the
+        // padding bytes (up to 31) are within the already-allocated region and guaranteed to be zero by
+        // Solidity's virgin-memory invariant. The zeros are the intended table padding per the metadata format.
         uint256 paddedLength =
             newMetadata.length % WORD_SIZE == 0 ? newMetadata.length : (newMetadata.length / WORD_SIZE + 1) * WORD_SIZE;
         assembly ("memory-safe") {
@@ -162,6 +169,9 @@ library JBMetadataResolver {
     function createMetadata(bytes4[] memory ids, bytes[] memory datas) internal pure returns (bytes memory metadata) {
         if (ids.length != datas.length) revert JBMetadataResolver_LengthMismatch();
 
+        // Return empty bytes for empty input arrays to avoid underflow in offset calculation below.
+        if (ids.length == 0) return bytes("");
+
         // Add a first empty 32B for the protocol reserved word
         metadata = abi.encodePacked(bytes32(0));
 
@@ -218,6 +228,9 @@ library JBMetadataResolver {
 
     /// @notice Parse the metadata to find the data for a specific ID
     /// @dev Returns false and an empty bytes if no data is found
+    /// @dev Padding to 32-byte boundaries is required for ABI compatibility. The apparent
+    /// inconsistency between creation and parsing is intentional: creation pads for storage alignment,
+    /// parsing uses actual data length boundaries from the lookup table.
     /// @param id The ID to find.
     /// @param metadata The metadata to parse.
     /// @return found Whether the {id:data} was found

package/src/structs/JBBeforeCashOutRecordedContext.sol

@@ -16,6 +16,9 @@ import {JBTokenAmount} from "./JBTokenAmount.sol";
 /// included, and the currency of the surplus.
 /// @custom:member useTotalSurplus If surplus across all of a project's terminals is being used when making cash outs.
 /// @custom:member cashOutTaxRate The cash out tax rate of the ruleset the cash out is being made during.
+/// @custom:member beneficiaryIsFeeless Whether the cash out's beneficiary is a feeless address. Useful for data hooks
+/// that charge their own fees — they can skip fees when value stays in the protocol (e.g. project-to-project
+/// routing).
 /// @custom:member metadata Extra data provided by the casher.
 // forge-lint: disable-next-line(pascal-case-struct)
 struct JBBeforeCashOutRecordedContext {
@@ -28,5 +31,6 @@ struct JBBeforeCashOutRecordedContext {
     JBTokenAmount surplus;
     bool useTotalSurplus;
     uint256 cashOutTaxRate;
+    bool beneficiaryIsFeeless;
     bytes metadata;
 }