@bananapus/core-v6 0.0.54 → 0.0.57

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/core-v6",
-  "version": "0.0.54",
+  "version": "0.0.57",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -38,7 +38,7 @@
     "artifacts": "source ./.env && npx sphinx artifacts --org-id 'ea165b21-7cdc-4d7b-be59-ecdd4c26bee4' --project-name 'nana-core-v6'"
   },
   "dependencies": {
-    "@bananapus/permission-ids-v6": "^0.0.23",
+    "@bananapus/permission-ids-v6": "^0.0.26",
     "@chainlink/contracts": "1.5.0",
     "@openzeppelin/contracts": "5.6.1",
     "@prb/math": "4.1.1",

package/script/helpers/CoreDeploymentLib.sol

@@ -43,11 +43,10 @@ library CoreDeploymentLib {
     string constant PROJECT_NAME = "nana-core-v6";
 
     function getDeployment(string memory path) internal returns (CoreDeployment memory deployment) {
-        // get chainId for which we need to get the deployment.
+        // Match the current chain ID to the Sphinx network name used in deployment artifacts.
         uint256 chainId = block.chainid;
 
-        // Deploy to get the constants.
-        // TODO: get constants without deploy.
+        // `SphinxConstants` exposes Sphinx's supported chain ID to network name mapping.
         SphinxConstants sphinxConstants = new SphinxConstants();
         NetworkInfo[] memory networks = sphinxConstants.getNetworkInfoArray();
 

package/src/JBController.sol

@@ -67,6 +67,7 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
     error JBController_NoReservedTokens(uint256 projectId);
     error JBController_OnlyDirectory(address sender, IJBDirectory directory);
     error JBController_PendingReservedTokens(uint256 pendingReservedTokenBalance);
+    error JBController_ReservedTokenSplitProjectSameAsOwner(uint256 projectId);
     error JBController_RulesetsAlreadyLaunched(uint256 projectId);
     error JBController_RulesetsArrayEmpty(uint256 projectId, uint256 rulesetConfigurationCount);
     error JBController_RulesetSetTokenNotAllowed(uint256 projectId);
@@ -382,8 +383,10 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
     /// @notice Creates a new Juicebox project in one transaction — mints the project NFT, queues initial rulesets,
     /// and
     /// configures terminals. This is the primary entry point for launching a project.
-    /// @dev Anyone can call this on behalf of any owner. Each sub-operation (mint, queue, configure) can also be done
-    /// individually if needed.
+    /// @dev Anyone can call this on behalf of any owner. This is a launch convenience, not owner authorization proof:
+    /// frontends and operators must use the transaction sender, an explicit owner signature, or their own deployment
+    /// flow to decide whether the owner intentionally launched a configuration. Each sub-operation (mint, queue,
+    /// configure) can also be done individually if needed.
     /// @param owner The project's owner. The project ERC-721 will be minted to this address.
     /// @param projectUri The project's metadata URI. This is typically an IPFS hash, optionally with the `ipfs://`
     /// prefix. This can be updated by the project's owner.
@@ -1061,7 +1064,8 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
             JBSplit memory split = splits[i];
 
             // Calculate the amount to send to the split.
-            uint256 splitTokenCount = mulDiv(tokenCount, split.percent, JBConstants.SPLITS_TOTAL_PERCENT);
+            uint256 splitTokenCount =
+                mulDiv({x: tokenCount, y: split.percent, denominator: JBConstants.SPLITS_TOTAL_PERCENT});
 
             // Mints tokens for the split if needed.
             if (splitTokenCount > 0) {
@@ -1116,7 +1120,18 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
                     // sender.
                     address beneficiary = split.beneficiary != address(0) ? split.beneficiary : messageSender;
 
+                    // Reserved token splits with no project ID mint directly to the beneficiary. A non-zero project ID
+                    // takes the "pay another project" path, which treats the reserved tokens as revenue for the
+                    // destination project and can mint another batch of tokens according to its ruleset.
                     if (split.projectId != 0) {
+                        if (split.projectId == projectId) {
+                            // The source project is not a valid destination for the terminal-payment path.
+                            // `sendReservedTokensToSplitsOf` clears the pending reserve balance before this helper
+                            // runs. Paying those freshly minted reserves into the same project's terminal would book
+                            // them as new revenue, mint another batch of tokens, and start the reserve cycle again.
+                            revert JBController_ReservedTokenSplitProjectSameAsOwner({projectId: projectId});
+                        }
+
                         // Get a reference to the receiving project's primary payment terminal for the token.
                         IJBTerminal terminal = token == IJBToken(address(0))
                             ? IJBTerminal(address(0))
@@ -1264,8 +1279,11 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
         returns (uint256 beneficiaryTokenCount, uint256 reservedTokenCount)
     {
         // Compute the beneficiary's portion after removing the reserved share.
-        beneficiaryTokenCount =
-            mulDiv(tokenCount, JBConstants.MAX_RESERVED_PERCENT - reservedPercent, JBConstants.MAX_RESERVED_PERCENT);
+        beneficiaryTokenCount = mulDiv({
+            x: tokenCount,
+            y: JBConstants.MAX_RESERVED_PERCENT - reservedPercent,
+            denominator: JBConstants.MAX_RESERVED_PERCENT
+        });
 
         // The remaining tokens are reserved.
         reservedTokenCount = tokenCount - beneficiaryTokenCount;

package/src/JBERC20.sol

@@ -41,7 +41,7 @@ contract JBERC20 is ERC20Votes, ERC20Permit, JBPermissioned, IERC1271, IJBToken
 
     /// @notice The JBTokens contract that owns this token.
     /// @dev Set via `initialize` because JBERC20 is deployed before JBTokens (circular dependency).
-    IJBTokens public TOKENS;
+    IJBTokens public tokens;
 
     //*********************************************************************//
     // -------------------- private stored properties -------------------- //
@@ -80,7 +80,7 @@ contract JBERC20 is ERC20Votes, ERC20Permit, JBPermissioned, IERC1271, IJBToken
     /// @notice Only the JBTokens contract can call this function.
     // forge-lint: disable-next-line(unwrapped-modifier-logic)
     modifier onlyTokens() {
-        if (msg.sender != address(TOKENS)) revert JBERC20_Unauthorized({caller: msg.sender, tokens: address(TOKENS)});
+        if (msg.sender != address(tokens)) revert JBERC20_Unauthorized({caller: msg.sender, tokens: address(tokens)});
         _;
     }
 
@@ -130,11 +130,11 @@ contract JBERC20 is ERC20Votes, ERC20Permit, JBPermissioned, IERC1271, IJBToken
     /// @return magicValue `0x1626ba7e` if the signature is valid, `0xffffffff` otherwise.
     function isValidSignature(bytes32 hash, bytes memory signature) external view override returns (bytes4 magicValue) {
         // Recover the signer from the signature. Return invalid if recovery fails.
-        (address signer, ECDSA.RecoverError error,) = ECDSA.tryRecover(hash, signature);
+        (address signer, ECDSA.RecoverError error,) = ECDSA.tryRecover({hash: hash, signature: signature});
         if (error != ECDSA.RecoverError.NoError) return 0xffffffff;
 
         // Get the project ID this token belongs to.
-        uint256 projectId = TOKENS.projectIdOf(IJBToken(address(this)));
+        uint256 projectId = tokens.projectIdOf(IJBToken(address(this)));
 
         // Get the project owner (the NFT holder).
         address projectOwner = PROJECTS.ownerOf(projectId);
@@ -195,8 +195,8 @@ contract JBERC20 is ERC20Votes, ERC20Permit, JBPermissioned, IERC1271, IJBToken
     /// @notice Initialize a new project token with the given name, symbol, and owner.
     /// @param name_ The token's name.
     /// @param symbol_ The token's symbol.
-    /// @param tokens The JBTokens contract that manages this token.
-    function initialize(string memory name_, string memory symbol_, address tokens) public override {
+    /// @param tokensAddress The JBTokens contract that manages this token.
+    function initialize(string memory name_, string memory symbol_, address tokensAddress) public override {
         // Prevent re-initialization by reverting if a name is already set or if the provided name is empty.
         if (bytes(_name).length != 0 || bytes(name_).length == 0) {
             revert JBERC20_AlreadyInitialized({
@@ -206,7 +206,7 @@ contract JBERC20 is ERC20Votes, ERC20Permit, JBPermissioned, IERC1271, IJBToken
 
         _name = name_;
         _symbol = symbol_;
-        TOKENS = IJBTokens(tokens);
+        tokens = IJBTokens(tokensAddress);
     }
 
     //*********************************************************************//

package/src/JBFeelessAddresses.sol

@@ -5,12 +5,28 @@ import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";
 import {IERC165} from "@openzeppelin/contracts/utils/introspection/IERC165.sol";
 
 import {IJBFeelessAddresses} from "./interfaces/IJBFeelessAddresses.sol";
+import {IJBFeelessHook} from "./interfaces/IJBFeelessHook.sol";
 
 /// @notice A registry of addresses exempt from the protocol's 2.5% fee. Feeless addresses don't incur fees on
 /// payouts they receive, surplus allowance they use, or cash outs where they are the beneficiary.
 /// @dev All feeless status is managed by the contract owner (typically the protocol multisig).
 /// @dev `projectId = 0` is the wildcard — an address feeless for project 0 is feeless for ALL projects.
 contract JBFeelessAddresses is Ownable, IJBFeelessAddresses, IERC165 {
+    //*********************************************************************//
+    // --------------------------- custom errors ------------------------- //
+    //*********************************************************************//
+
+    error JBFeelessAddresses_InvalidFeelessHook(IJBFeelessHook hook);
+
+    //*********************************************************************//
+    // --------------------- public stored properties -------------------- //
+    //*********************************************************************//
+
+    /// @notice Optional hook consulted (in addition to the static mappings) when computing feeless status.
+    /// @dev OR'd with the mappings — the hook can only widen the feeless set, never shrink it. `address(0)` disables
+    /// hook consultation.
+    IJBFeelessHook public override feelessHook;
+
     //*********************************************************************//
     // -------------------- internal stored properties ------------------- //
     //*********************************************************************//
@@ -53,19 +69,54 @@ contract JBFeelessAddresses is Ownable, IJBFeelessAddresses, IERC165 {
         emit SetFeelessAddress({projectId: projectId, addr: addr, isFeeless: flag, caller: _msgSender()});
     }
 
+    /// @notice Sets (or clears) the feeless hook consulted by `isFeelessFor`.
+    /// @dev Can only be called by this contract's owner (typically the protocol multisig).
+    /// @dev If `hook` is non-zero, it must report ERC-165 support for `IJBFeelessHook` or this call reverts.
+    /// @param hook The new hook. Pass `address(0)` to disable hook consultation.
+    function setFeelessHook(IJBFeelessHook hook) external virtual override onlyOwner {
+        if (address(hook) != address(0) && !hook.supportsInterface(type(IJBFeelessHook).interfaceId)) {
+            revert JBFeelessAddresses_InvalidFeelessHook(hook);
+        }
+
+        feelessHook = hook;
+
+        emit SetFeelessHook({hook: hook, caller: _msgSender()});
+    }
+
     //*********************************************************************//
-    // -------------------------- public views --------------------------- //
+    // ------------------------- external views -------------------------- //
     //*********************************************************************//
 
-    /// @notice Returns whether the specified address is feeless for a specific project, considering both the wildcard
-    /// (projectId 0) and project-specific feeless status.
+    /// @notice Returns whether the specified address is feeless for a specific project, providing the outer caller
+    /// of the fee-bearing operation so hooks can scope grants by who initiated the action.
+    /// @dev The static admin-set mappings are caller-agnostic and always apply. The hook (if set) receives `caller`
+    /// (typically the terminal's `_msgSender()`) and may use it to narrow its grant — e.g. grant an ecosystem
+    /// router feeless cash-outs only when the router itself is the caller, not when it appears as a split recipient
+    /// of someone else's payout. Hook is invoked via try/catch — a reverting hook is treated as `false`.
     /// @param addr The address to check.
     /// @param projectId The ID of the project to check.
-    /// @return A flag indicating whether the address is feeless (globally or for the project).
-    function isFeelessFor(address addr, uint256 projectId) external view override returns (bool) {
-        return _isFeelessFor[0][addr] || _isFeelessFor[projectId][addr];
+    /// @param caller The outer caller (typically the terminal's `_msgSender()`). Pass `address(0)` for lookups
+    /// without caller context.
+    /// @return A flag indicating whether the address is feeless.
+    function isFeelessFor(address addr, uint256 projectId, address caller) external view override returns (bool) {
+        // Static grants are administrative and do not depend on who triggered the fee-bearing operation.
+        if (_isFeelessFor[0][addr] || _isFeelessFor[projectId][addr]) return true;
+
+        IJBFeelessHook hook = feelessHook;
+        if (address(hook) == address(0)) return false;
+
+        // Hook grants are optional and caller-aware; a reverting hook is treated as "not feeless".
+        try hook.isFeeless({projectId: projectId, addr: addr, caller: caller}) returns (bool result) {
+            return result;
+        } catch {
+            return false;
+        }
     }
 
+    //*********************************************************************//
+    // -------------------------- public views --------------------------- //
+    //*********************************************************************//
+
     /// @notice Indicates whether this contract adheres to the specified interface.
     /// @dev See {IERC165-supportsInterface}.
     /// @param interfaceId The ID of the interface to check for adherence to.

package/src/JBFundAccessLimits.sol

@@ -18,6 +18,9 @@ contract JBFundAccessLimits is JBControlled, IJBFundAccessLimits {
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
+    error JBFundAccessLimits_DuplicateFundAccessLimitGroup(
+        uint256 projectId, uint256 rulesetId, uint256 groupIndex, address terminal, address token
+    );
     error JBFundAccessLimits_InvalidPayoutLimitCurrencyOrdering(
         uint256 projectId, uint256 rulesetId, uint256 groupIndex, uint256 limitIndex
     );
@@ -95,6 +98,28 @@ contract JBFundAccessLimits is JBControlled, IJBFundAccessLimits {
             // Set the limits being iterated on.
             JBFundAccessLimitGroup calldata fundAccessLimitGroup = fundAccessLimitGroups[i];
 
+            // Each terminal/token pair should have exactly one group. The per-group currency ordering checks below
+            // prevent duplicate currencies inside one group; this prevents splitting a duplicate currency across two
+            // groups for the same terminal/token pair.
+            for (uint256 j; j < i;) {
+                JBFundAccessLimitGroup calldata previousGroup = fundAccessLimitGroups[j];
+                if (
+                    previousGroup.terminal == fundAccessLimitGroup.terminal
+                        && previousGroup.token == fundAccessLimitGroup.token
+                ) {
+                    revert JBFundAccessLimits_DuplicateFundAccessLimitGroup({
+                        projectId: projectId,
+                        rulesetId: rulesetId,
+                        groupIndex: i,
+                        terminal: fundAccessLimitGroup.terminal,
+                        token: fundAccessLimitGroup.token
+                    });
+                }
+                unchecked {
+                    ++j;
+                }
+            }
+
             // Keep a reference to the number of payout limits.
             uint256 numberOfPayoutLimits = fundAccessLimitGroup.payoutLimits.length;
 

package/src/JBMultiTerminal.sol

@@ -64,14 +64,16 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     //*********************************************************************//
 
     error JBMultiTerminal_FeeTerminalNotFound(address token);
-    error JBMultiTerminal_MintNotAllowed(uint256 projectId, uint256 splitProjectId, address terminal);
+    error JBMultiTerminal_MintNotAllowed();
     error JBMultiTerminal_NoMsgValueAllowed(uint256 value);
     error JBMultiTerminal_OverflowAlert(uint256 value, uint256 limit);
     error JBMultiTerminal_PermitAllowanceNotEnough(uint256 amount, uint256 allowance);
     error JBMultiTerminal_RecipientProjectTerminalNotFound(uint256 projectId, address token);
+    error JBMultiTerminal_ReentrantTokenTransfer(address token);
     error JBMultiTerminal_SplitHookInvalid(IJBSplitHook hook);
-    error JBMultiTerminal_TerminalTokensIncompatible(uint256 projectId, address token, IJBTerminal terminal);
     error JBMultiTerminal_TemporaryAllowanceNotConsumed(address token, address spender, uint256 allowance);
+    error JBMultiTerminal_TerminalMigrationToSelf(uint256 projectId, address token);
+    error JBMultiTerminal_TerminalTokensIncompatible(uint256 projectId, address token, IJBTerminal terminal);
     error JBMultiTerminal_TokenNotAccepted(address token);
     error JBMultiTerminal_UnderMin(uint256 value, uint256 min);
 
@@ -140,6 +142,18 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     /// @custom:param token The token the fees are held in.
     mapping(uint256 projectId => mapping(address token => uint256)) internal _nextHeldFeeIndexOf;
 
+    //*********************************************************************//
+    // ------------------- transient stored properties ------------------- //
+    //*********************************************************************//
+
+    /// @notice Whether this terminal is currently measuring an incoming ERC-20 balance delta.
+    bool transient _acceptingToken;
+
+    /// @notice Source project ID for the same-terminal split pay currently being recorded.
+    /// @dev After `_pay` consumes and clears this value, `_fulfillPayHookSpecificationsFor` reuses the slot to return
+    /// the fee basis to `executePayout`.
+    uint256 transient _internalSplitPayProjectId;
+
     //*********************************************************************//
     // -------------------------- constructor ---------------------------- //
     //*********************************************************************//
@@ -326,6 +340,8 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             }
 
             if (!_isFeeless({addr: address(split.hook), projectId: projectId})) {
+                // Split hooks pull funds out of this terminal, so non-feeless hooks receive the net amount after
+                // the standard terminal fee.
                 unchecked {
                     netPayoutAmount -= _feeAmountFrom(amount);
                 }
@@ -347,6 +363,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         } else if (split.projectId != 0) {
             // Get a reference to the terminal being used.
             IJBTerminal terminal = _primaryTerminalOf({projectId: split.projectId, token: token});
+            bool isThisTerminal = terminal == this;
 
             // The project must have a terminal to send funds to.
             if (terminal == IJBTerminal(address(0))) {
@@ -358,7 +375,9 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             // 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 feeless address.
-            if (terminal != this && !_isFeeless({addr: address(terminal), projectId: projectId})) {
+            if (!isThisTerminal && !_isFeeless({addr: address(terminal), projectId: projectId})) {
+                // Cross-terminal payouts leave this terminal's custody, so charge the standard terminal fee unless
+                // the recipient terminal is feeless.
                 unchecked {
                     netPayoutAmount -= _feeAmountFrom(amount);
                 }
@@ -367,9 +386,22 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
 
             // 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;
-            }
+            // Revert on any self-referencing payout (the source project paying itself via a split),
+            // regardless of which terminal receives the call or which branch (pay vs add-to-balance)
+            // is taken. Both shapes are disguised owner actions that the payout pipeline must not
+            // silently authorize:
+            //   - pay branch: the destination terminal's `pay()` mints new project tokens against
+            //     the project's own surplus, diluting holders out-of-cycle and bypassing the
+            //     ruleset's `allowOwnerMinting=false` guarantee. This holds even when the
+            //     destination terminal is a different instance owned by the same project, because
+            //     every registered terminal can mint via the terminal-as-minter pathway.
+            //   - addToBalance branch: a same-project add-balance split shuffles surplus between
+            //     the project's own terminals through the payout pipeline. The same effect is
+            //     available via `addToBalanceOf` directly without the side effects (locked-split
+            //     consumption, payout-limit drawdown, fee-free-surplus accounting); routing it
+            //     through `sendPayoutsOf` is never the right surface.
+            // The try-catch in the split group lib catches this revert and restores the balance.
+            if (split.projectId == projectId) revert JBMultiTerminal_MintNotAllowed();
 
             // Send the `projectId` in the metadata as a referral.
             bytes memory metadata = bytes(abi.encodePacked(projectId));
@@ -383,21 +415,20 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
                     amount: netPayoutAmount,
                     metadata: metadata
                 });
-            } else {
-                // Revert if this is a self-referencing payout (project paying itself via a split).
-                // Same-project pay splits would mint tokens against existing balance without new funds entering.
-                // Projects that want to mint should do so explicitly via the controller.
-                // Cross-project pay splits on the same terminal are allowed (different project receives the funds).
-                // The try-catch in the split group lib catches this revert and restores the balance.
-                if (terminal == this && split.projectId == projectId) {
-                    revert JBMultiTerminal_MintNotAllowed({
-                        projectId: projectId, splitProjectId: split.projectId, terminal: address(terminal)
-                    });
-                }
 
+                // Same-terminal adds never invoke destination pay hooks, so the full amount remains in the
+                // destination project's balance and must be fee-liable on its later zero-tax cashout.
+                if (isThisTerminal) _feeFreeSurplusOf[split.projectId][token] += netPayoutAmount;
+            } else {
                 // Keep a reference to the beneficiary of the payment.
                 address beneficiary = split.beneficiary != address(0) ? split.beneficiary : originalMessageSender;
 
+                // Mark same-terminal split pays so `_pay` can fee pay-hook forwards inline and track only retained
+                // value as fee-free surplus.
+                if (isThisTerminal) {
+                    _internalSplitPayProjectId = projectId;
+                }
+
                 _efficientPay({
                     terminal: terminal,
                     projectId: split.projectId,
@@ -407,12 +438,10 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
                     metadata: metadata
                 });
 
-                // Cap fee-free surplus at remaining balance.
-                // Why: _feeFreeSurplusOf was incremented by the full netPayoutAmount above, but if the
-                // destination project's data hook forwarded part of the payment to pay hooks, the store
-                // only recorded a partial balance increase. Without this cap, _feeFreeSurplusOf can exceed
-                // STORE.balanceOf, causing users to be overcharged fees on zero-tax cashouts.
-                _capFeeFreeSurplus({projectId: split.projectId, token: token});
+                if (isThisTerminal) {
+                    feeEligibleAmount += _internalSplitPayProjectId;
+                    delete _internalSplitPayProjectId;
+                }
             }
         } else {
             // If there's a beneficiary, send the funds directly to the beneficiary.
@@ -423,6 +452,8 @@ 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({addr: recipient, projectId: projectId})) {
+                // Direct payouts leave the terminal, so non-feeless recipients receive the net amount after the
+                // standard terminal fee.
                 unchecked {
                     netPayoutAmount -= _feeAmountFrom(amount);
                 }
@@ -507,6 +538,12 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             account: _ownerOf(projectId), projectId: projectId, permissionId: JBPermissionIds.MIGRATE_TERMINAL
         });
 
+        // Migrating to the same terminal would zero this terminal's store balance and then try to re-add it through
+        // the external terminal interface. ERC-20 self-transfers produce no balance delta, leaving funds stranded.
+        if (address(to) == address(this)) {
+            revert JBMultiTerminal_TerminalMigrationToSelf({projectId: projectId, token: token});
+        }
+
         // The terminal being migrated to must accept the same token as this terminal.
         if (to.accountingContextForTokenOf({projectId: projectId, token: token}).currency == 0) {
             revert JBMultiTerminal_TerminalTokensIncompatible({projectId: projectId, token: token, terminal: to});
@@ -531,6 +568,9 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             // This also settles any fee-free surplus liability that would otherwise be lost on the new terminal.
             uint256 feeAmount;
             if (!_isFeeless({addr: address(to), projectId: projectId}) && projectId != _FEE_BENEFICIARY_PROJECT_ID) {
+                // Fee processing failures never block migration. If the fee route is broken, `_processFee` credits
+                // the fee amount back to this source terminal and emits `FeeReverted`; the post-fee amount still
+                // migrates so project funds are not trapped behind project #1 routing issues.
                 feeAmount = _takeFeeFrom({
                     projectId: projectId,
                     token: token,
@@ -654,7 +694,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             delete _heldFeesOf[projectId][token][currentIndex];
             _nextHeldFeeIndexOf[projectId][token] = currentIndex + 1;
 
-            // Process the fee.
+            // Process the standard fee on the original gross amount recorded when the held fee was created.
             _processFee({
                 projectId: projectId,
                 token: token,
@@ -1028,11 +1068,20 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         // Get a reference to the balance before receiving tokens.
         uint256 balanceBefore = _balanceOf(token);
 
+        // Prevent callback-capable tokens from nesting another incoming ERC-20 transfer inside this balance-delta
+        // measurement.
+        if (_acceptingToken) revert JBMultiTerminal_ReentrantTokenTransfer(token);
+        _acceptingToken = true;
+
         // Transfer tokens to this terminal from the msg sender.
         _transferFrom({from: _msgSender(), to: payable(address(this)), token: token, amount: amount});
 
         // The amount should reflect the change in balance.
-        return _balanceOf(token) - balanceBefore;
+        uint256 acceptedAmount = _balanceOf(token) - balanceBefore;
+
+        _acceptingToken = false;
+
+        return acceptedAmount;
     }
 
     /// @notice Adds funds to a project's balance without minting tokens.
@@ -1346,6 +1395,34 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         }
     }
 
+    /// @notice Emits a `Pay` event. Extracted from `_pay` so the 9-field event payload gets its own stack frame —
+    /// inlining the emit into `_pay` overflows the non-IR build's stack budget.
+    function _emitPay(
+        JBRuleset memory ruleset,
+        uint256 projectId,
+        address payer,
+        address beneficiary,
+        uint256 amount,
+        uint256 newlyIssuedTokenCount,
+        string memory memo,
+        bytes memory metadata
+    )
+        internal
+    {
+        emit Pay({
+            rulesetId: ruleset.id,
+            rulesetCycleNumber: ruleset.cycleNumber,
+            projectId: projectId,
+            payer: payer,
+            beneficiary: beneficiary,
+            amount: amount,
+            newlyIssuedTokenCount: newlyIssuedTokenCount,
+            memo: memo,
+            metadata: metadata,
+            caller: _msgSender()
+        });
+    }
+
     /// @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 to fund.
@@ -1433,7 +1510,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
                 continue;
             }
 
-            // Get the fee for the specified amount.
+            // Cash-out hooks receive the net amount after the standard fee unless the hook is feeless.
             uint256 specificationAmountFee = _isFeeless({addr: address(specification.hook), projectId: projectId})
                 ? 0
                 : _feeAmountFrom(specification.amount);
@@ -1489,6 +1566,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     /// @param beneficiary The address which will receive any tokens that the payment yields.
     /// @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.
+    /// @param internalSplitPayProjectId The source project when this payment came from a same-terminal split.
     function _fulfillPayHookSpecificationsFor(
         uint256 projectId,
         JBPayHookSpecification[] memory specifications,
@@ -1497,10 +1575,13 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         JBRuleset memory ruleset,
         address beneficiary,
         uint256 newlyIssuedTokenCount,
-        bytes memory metadata
+        bytes memory metadata,
+        uint256 internalSplitPayProjectId
     )
         internal
     {
+        uint256 amountEligibleForFees;
+
         // Keep a reference to payment context for the pay hooks.
         JBAfterPayRecordedContext memory context = JBAfterPayRecordedContext({
             payer: payer,
@@ -1528,9 +1609,25 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
                 continue;
             }
 
+            uint256 specificationAmount = specification.amount;
+
+            if (
+                internalSplitPayProjectId != 0
+                    && !_isFeeless({addr: address(specification.hook), projectId: internalSplitPayProjectId})
+            ) {
+                // Same-terminal split pays defer source-side fees until the destination data hook is known. Net
+                // non-feeless hook forwards here so they match ordinary payout semantics before funds leave.
+                // Keep the fee basis local until every hook returns. Writing the transient accumulator before the
+                // hook call would let a reentrant payout overwrite the outer split's pending fee basis.
+                unchecked {
+                    amountEligibleForFees += specificationAmount;
+                    specificationAmount -= _feeAmountFrom(specificationAmount);
+                }
+            }
+
             // Pass the correct token `forwardedAmount` to the hook.
             context.forwardedAmount = JBTokenAmount({
-                value: specification.amount,
+                value: specificationAmount,
                 token: tokenAmount.token,
                 decimals: tokenAmount.decimals,
                 currency: tokenAmount.currency
@@ -1542,7 +1639,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             // Trigger any inherited pre-transfer logic.
             // Keep a reference to the amount that'll be paid as a `msg.value`.
             uint256 payValue = _beforeTransferTo({
-                to: address(specification.hook), token: tokenAmount.token, amount: specification.amount
+                to: address(specification.hook), token: tokenAmount.token, amount: specificationAmount
             });
 
             // Fulfill the specification.
@@ -1554,13 +1651,17 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             emit HookAfterRecordPay({
                 hook: specification.hook,
                 context: context,
-                specificationAmount: specification.amount,
+                specificationAmount: specificationAmount,
                 caller: _msgSender()
             });
             unchecked {
                 ++i;
             }
         }
+
+        // `_pay` consumed and cleared the source project ID before calling hooks, so the transient slot can now carry
+        // the hook-derived fee basis back to `executePayout`. Publish it only after all untrusted hook calls return.
+        _internalSplitPayProjectId = amountEligibleForFees;
     }
 
     /// @notice Internal implementation of payment logic. Records the payment in the store, mints tokens via the
@@ -1586,6 +1687,11 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     )
         internal
     {
+        // Same-terminal split pays are the only inbound pays whose source-side fee was intentionally deferred. Cache
+        // and clear the transient source project before untrusted data/pay hooks can reenter ordinary pay flows.
+        uint256 internalSplitPayProjectId = _internalSplitPayProjectId;
+        if (internalSplitPayProjectId != 0) delete _internalSplitPayProjectId;
+
         // Keep a reference to the token amount to forward to the store.
         JBTokenAmount memory tokenAmount = _tokenAmountOf({projectId: projectId, token: token, value: amount});
 
@@ -1597,6 +1703,20 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             payer: payer, amount: tokenAmount, projectId: projectId, beneficiary: beneficiary, metadata: metadata
         });
 
+        // Only the value retained in the destination balance needs later cashout fee recovery. Non-feeless pay-hook
+        // forwards pay their source-equivalent fee inline before leaving the project.
+        if (internalSplitPayProjectId != 0) {
+            uint256 feeFreeAmount = tokenAmount.value;
+            for (uint256 i; i < hookSpecifications.length;) {
+                // The store already proved the hook-spec total does not exceed the pay amount.
+                unchecked {
+                    feeFreeAmount -= hookSpecifications[i].amount;
+                    ++i;
+                }
+            }
+            _feeFreeSurplusOf[projectId][token] += feeFreeAmount;
+        }
+
         // Keep a reference to the number of tokens issued for the beneficiary.
         uint256 newlyIssuedTokenCount;
 
@@ -1614,17 +1734,19 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             });
         }
 
-        emit Pay({
-            rulesetId: ruleset.id,
-            rulesetCycleNumber: ruleset.cycleNumber,
+        // `_pay` already carries ~10 locals (ruleset, tokenCount, hookSpecifications, balanceDiff, tokenAmount,
+        // newlyIssuedTokenCount, internalSplitPayProjectId, feeFreeAmount, plus loop-local `i` and `hookAmount`).
+        // Inlining the 9-arg `emit Pay` here hits "Stack too deep" under the non-IR build, so the emit is extracted
+        // to `_emitPay` which gets its own stack frame.
+        _emitPay({
+            ruleset: ruleset,
             projectId: projectId,
             payer: payer,
             beneficiary: beneficiary,
             amount: amount,
             newlyIssuedTokenCount: newlyIssuedTokenCount,
             memo: memo,
-            metadata: metadata,
-            caller: _msgSender()
+            metadata: metadata
         });
 
         // If the data hook returned pay hook specifications, fulfill them.
@@ -1637,7 +1759,8 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
                 ruleset: ruleset,
                 beneficiary: beneficiary,
                 newlyIssuedTokenCount: newlyIssuedTokenCount,
-                metadata: metadata
+                metadata: metadata,
+                internalSplitPayProjectId: internalSplitPayProjectId
             });
         }
     }
@@ -1649,6 +1772,8 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     /// @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 to process was held by this terminal.
+    /// @dev Fee-route failures are forgiven instead of reverted so project funds cannot be trapped by project #1
+    /// misconfiguration. The failed fee amount is credited back to the payer project's balance on this terminal.
     function _processFee(
         uint256 projectId,
         address token,
@@ -1671,10 +1796,9 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
                 caller: _msgSender()
             });
         } catch (bytes memory reason) {
-            // Fee processing failed — intentionally forgive the fee and return the amount to the project.
-            // The held-fee entry (if any) was already deleted by `processHeldFeesOf` before this call, so there is no
-            // retry path. This is by design: a broken or misconfigured fee route should not permanently lock project
-            // funds. The `FeeReverted` event makes this observable off-chain.
+            // Fee processing is fail-open for project liveness: a broken project #1 terminal or fee route must not
+            // trap payouts, cash outs, allowances, held-fee processing, or terminal migration. The fee is forgiven,
+            // credited back to the originating project on this terminal, and surfaced through `FeeReverted`.
             emit FeeReverted({
                 projectId: projectId,
                 token: token,
@@ -1727,6 +1851,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
             // Held fees store the original gross amount that paid out before its fee was removed.
             JBFee memory heldFee = _heldFeesOf[projectId][token][i];
 
+            // Recompute the standard fee associated with the held gross amount.
             uint256 feeAmount = _feeAmountFrom(heldFee.amount);
 
             // This is the net amount that originally left the project after the held fee was removed.
@@ -1892,7 +2017,8 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     /// accounting context.
     /// @param beneficiary The address to mint the platform's project's tokens for.
     /// @param shouldHoldFees If fees should be tracked and held instead of processing them immediately.
-    /// @return feeAmount The amount of the fee taken.
+    /// @return feeAmount The fee withheld from the current outflow. If immediate fee processing fails, `_processFee`
+    /// credits this amount back to the payer project while the current outflow continues.
     function _takeFeeFrom(
         uint256 projectId,
         address token,
@@ -2098,11 +2224,14 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     }
 
     /// @notice Returns a flag indicating if interacting with an address should not incur fees.
+    /// @dev Forwards `_msgSender()` (the outer caller of the terminal, with ERC-2771 forwarders unwrapped) to the
+    /// registry so an installed feeless hook can scope its grant by caller — e.g. recognise an ecosystem router
+    /// that wraps cash-out → pay and grant it fee-free cash-outs only when it itself is the caller.
     /// @param addr The address to check.
     /// @param projectId The ID of the project to check the per-project feeless status for.
     /// @return A flag indicating if the address should not incur fees (globally or for the project).
     function _isFeeless(address addr, uint256 projectId) internal view returns (bool) {
-        return FEELESS_ADDRESSES.isFeelessFor({addr: addr, projectId: projectId});
+        return FEELESS_ADDRESSES.isFeelessFor({addr: addr, projectId: projectId, caller: _msgSender()});
     }
 
     /// @notice The calldata. Preferred to use over `msg.data`.

package/src/JBPrices.sol

@@ -27,6 +27,7 @@ contract JBPrices is JBControlled, JBPermissioned, ERC2771Context, Ownable, IJBP
 
     error JBPrices_PriceFeedAlreadyExists(IJBPriceFeed feed);
     error JBPrices_PriceFeedNotFound(uint256 projectId, uint256 pricingCurrency, uint256 unitCurrency);
+    error JBPrices_ZeroPrice(uint256 projectId, uint256 pricingCurrency, uint256 unitCurrency, IJBPriceFeed feed);
     error JBPrices_ZeroPricingCurrency(uint256 projectId, uint256 pricingCurrency);
     error JBPrices_ZeroUnitCurrency(uint256 projectId, uint256 unitCurrency);
 
@@ -191,8 +192,16 @@ contract JBPrices is JBControlled, JBPermissioned, ERC2771Context, Ownable, IJBP
         // Get a reference to the price feed.
         IJBPriceFeed feed = priceFeedFor[projectId][pricingCurrency][unitCurrency];
 
-        // If the feed exists, return its price.
-        if (feed != IJBPriceFeed(address(0))) return feed.currentUnitPrice(decimals);
+        // If the feed exists, return its non-zero price.
+        if (feed != IJBPriceFeed(address(0))) {
+            uint256 price = feed.currentUnitPrice(decimals);
+            if (price == 0) {
+                revert JBPrices_ZeroPrice({
+                    projectId: projectId, pricingCurrency: pricingCurrency, unitCurrency: unitCurrency, feed: feed
+                });
+            }
+            return price;
+        }
 
         // Try getting the inverse feed.
         feed = priceFeedFor[projectId][unitCurrency][pricingCurrency];
@@ -202,7 +211,13 @@ contract JBPrices is JBControlled, JBPermissioned, ERC2771Context, Ownable, IJBP
         // is in the range of ~1e9 to ~1e27 (for 18 decimals). Extreme prices outside this range may lose
         // significant precision due to fixed-point division truncation.
         if (feed != IJBPriceFeed(address(0))) {
-            return mulDiv(10 ** decimals, 10 ** decimals, feed.currentUnitPrice(decimals));
+            uint256 inversePrice = feed.currentUnitPrice(decimals);
+            if (inversePrice == 0) {
+                revert JBPrices_ZeroPrice({
+                    projectId: projectId, pricingCurrency: unitCurrency, unitCurrency: pricingCurrency, feed: feed
+                });
+            }
+            return mulDiv({x: 10 ** decimals, y: 10 ** decimals, denominator: inversePrice});
         }
 
         // Check for a default feed (project ID 0) if not found.

package/src/JBRulesets.sol

@@ -623,11 +623,11 @@ contract JBRulesets is JBControlled, IJBRulesets {
     {
         // A subsequent ruleset to one with a duration of 0 should have the next possible weight.
         if (baseRulesetDuration == 0) {
-            return mulDiv(
-                baseRulesetWeight,
-                JBConstants.MAX_WEIGHT_CUT_PERCENT - baseRulesetWeightCutPercent,
-                JBConstants.MAX_WEIGHT_CUT_PERCENT
-            );
+            return mulDiv({
+                x: baseRulesetWeight,
+                y: JBConstants.MAX_WEIGHT_CUT_PERCENT - baseRulesetWeightCutPercent,
+                denominator: JBConstants.MAX_WEIGHT_CUT_PERCENT
+            });
         }
 
         // The weight should be based off the base ruleset's weight.
@@ -673,7 +673,7 @@ contract JBRulesets is JBControlled, IJBRulesets {
 
         for (uint256 i; i < weightCutMultiple;) {
             // Base the new weight on the specified ruleset's weight.
-            weight = mulDiv(weight, cutFactor, maxPercent);
+            weight = mulDiv({x: weight, y: cutFactor, denominator: maxPercent});
 
             // The calculation doesn't need to continue if the weight is 0.
             if (weight == 0) break;

package/src/JBSplits.sol

@@ -173,14 +173,30 @@ contract JBSplits is JBControlled, IJBSplits {
         uint256 numberOfCurrentSplits = currentSplits.length;
 
         // Check to see if all locked splits are included in the array of splits which is being set.
+        // Duplicate locked splits must be preserved with the same multiplicity. Otherwise a table with two identical
+        // locked splits could be collapsed into one matching split and one unrelated split while each old split sees
+        // the same new match.
         for (uint256 i; i < numberOfCurrentSplits;) {
             // If not locked, continue.
-            if (
-                // forge-lint: disable-next-line(block-timestamp)
-                block.timestamp < currentSplits[i].lockedUntil
-                    && !_includesLockedSplits({splits: splits, lockedSplit: currentSplits[i]})
-            ) {
-                revert JBSplits_PreviousLockedSplitsNotIncluded({projectId: projectId, rulesetId: rulesetId});
+            // forge-lint: disable-next-line(block-timestamp)
+            if (block.timestamp < currentSplits[i].lockedUntil) {
+                uint256 requiredCount;
+                for (uint256 j; j < numberOfCurrentSplits;) {
+                    if (
+                        // forge-lint: disable-next-line(block-timestamp)
+                        block.timestamp < currentSplits[j].lockedUntil
+                            && _isLockedSplitIncluded({split: currentSplits[j], lockedSplit: currentSplits[i]})
+                    ) {
+                        ++requiredCount;
+                    }
+                    unchecked {
+                        ++j;
+                    }
+                }
+
+                if (_includedLockedSplitCount({splits: splits, lockedSplit: currentSplits[i]}) < requiredCount) {
+                    revert JBSplits_PreviousLockedSplitsNotIncluded({projectId: projectId, rulesetId: rulesetId});
+                }
             }
             unchecked {
                 ++i;
@@ -332,31 +348,38 @@ contract JBSplits is JBControlled, IJBSplits {
         return splits;
     }
 
-    /// @notice Determine if the provided splits array includes the locked split.
+    /// @notice Count the splits in the provided array that include the locked split.
     /// @param splits The array of splits to check within.
     /// @param lockedSplit The locked split.
-    /// @return A flag indicating if the `lockedSplit` is contained in the `splits`.
-    function _includesLockedSplits(JBSplit[] memory splits, JBSplit memory lockedSplit) internal pure returns (bool) {
+    /// @return count The number of matching splits.
+    function _includedLockedSplitCount(
+        JBSplit[] memory splits,
+        JBSplit memory lockedSplit
+    )
+        internal
+        pure
+        returns (uint256 count)
+    {
         // Keep a reference to the number of splits.
         uint256 numberOfSplits = splits.length;
 
         for (uint256 i; i < numberOfSplits;) {
-            // Set the split being iterated on.
-            JBSplit memory split = splits[i];
-
-            // Check for sameness.
-            if (
-                // Allow the lock to be extended.
-                split.percent == lockedSplit.percent && split.beneficiary == lockedSplit.beneficiary
-                    && split.hook == lockedSplit.hook && split.projectId == lockedSplit.projectId
-                    && split.preferAddToBalance == lockedSplit.preferAddToBalance
-                    && split.lockedUntil >= lockedSplit.lockedUntil
-            ) return true;
+            if (_isLockedSplitIncluded({split: splits[i], lockedSplit: lockedSplit})) ++count;
             unchecked {
                 ++i;
             }
         }
+    }
 
-        return false;
+    /// @notice Determine if a split satisfies the locked split's immutable fields and lock length.
+    /// @param split The split to check.
+    /// @param lockedSplit The locked split.
+    /// @return A flag indicating whether the split includes the locked split.
+    function _isLockedSplitIncluded(JBSplit memory split, JBSplit memory lockedSplit) internal pure returns (bool) {
+        // Allow the lock to be extended.
+        return split.percent == lockedSplit.percent && split.beneficiary == lockedSplit.beneficiary
+            && split.hook == lockedSplit.hook && split.projectId == lockedSplit.projectId
+            && split.preferAddToBalance == lockedSplit.preferAddToBalance
+            && split.lockedUntil >= lockedSplit.lockedUntil;
     }
 }

package/src/JBTokens.sol

@@ -230,7 +230,7 @@ contract JBTokens is JBControlled, IJBTokens {
         });
 
         // Initialize the token.
-        token.initialize({name: name, symbol: symbol, tokens: address(this)});
+        token.initialize({name: name, symbol: symbol, tokensAddress: address(this)});
     }
 
     /// @notice Create new tokens for a holder. If the project has an ERC-20 deployed, tokens are minted directly to

package/src/interfaces/IJBFeelessAddresses.sol

@@ -1,6 +1,8 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.0;
 
+import {IJBFeelessHook} from "./IJBFeelessHook.sol";
+
 /// @notice Tracks addresses that are exempt from fees, both globally and on a per-project basis.
 /// @dev `projectId = 0` is the wildcard — an address feeless for project 0 is feeless for ALL projects.
 interface IJBFeelessAddresses {
@@ -11,12 +13,26 @@ interface IJBFeelessAddresses {
     /// @param caller The address that set the feeless status.
     event SetFeelessAddress(uint256 indexed projectId, address indexed addr, bool indexed isFeeless, address caller);
 
-    /// @notice Returns whether the specified address is feeless for a specific project, considering both the wildcard
-    /// (projectId 0) and project-specific feeless status.
+    /// @notice The optional hook (set by the owner) that can grant feeless status with arbitrary logic. Set to the
+    /// zero address to disable.
+    /// @param hook The new feeless hook. The zero address disables hook consultation.
+    /// @param caller The address that set the hook.
+    event SetFeelessHook(IJBFeelessHook indexed hook, address caller);
+
+    /// @notice The optional hook consulted (in addition to the static mappings) when computing feeless status.
+    /// @dev `address(0)` means no hook is set.
+    function feelessHook() external view returns (IJBFeelessHook);
+
+    /// @notice Returns whether the specified address is feeless for a specific project, providing the outer caller
+    /// of the fee-bearing operation so hooks can scope grants by who initiated the action.
+    /// @dev Static admin-set mappings are op-agnostic and always apply. The hook (if set) receives `caller` and may
+    /// use it to scope its grant (e.g. an ecosystem router can be feeless only when it itself is the caller).
     /// @param addr The address to check.
     /// @param projectId The ID of the project to check.
-    /// @return A flag indicating whether the address is feeless (globally or for the project).
-    function isFeelessFor(address addr, uint256 projectId) external view returns (bool);
+    /// @param caller The outer caller (typically the terminal's `_msgSender()`). Pass `address(0)` for lookups
+    /// without caller context.
+    /// @return A flag indicating whether the address is feeless.
+    function isFeelessFor(address addr, uint256 projectId, address caller) external view returns (bool);
 
     /// @notice Sets whether an address is feeless globally (for all projects).
     /// @param addr The address to set the feeless status of.
@@ -28,4 +44,8 @@ interface IJBFeelessAddresses {
     /// @param addr The address to set the feeless status of.
     /// @param flag A flag indicating whether the address should be feeless for the project.
     function setFeelessAddressFor(uint256 projectId, address addr, bool flag) external;
+
+    /// @notice Sets (or clears) the feeless hook consulted by `isFeelessFor`.
+    /// @param hook The new hook. Pass `address(0)` to disable hook consultation.
+    function setFeelessHook(IJBFeelessHook hook) external;
 }

package/src/interfaces/IJBFeelessHook.sol

@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+import {IERC165} from "@openzeppelin/contracts/utils/introspection/IERC165.sol";
+
+/// @notice Optional hook that can grant feeless status to addresses based on arbitrary off-chain or on-chain logic.
+/// @dev Plugged into `JBFeelessAddresses` by the contract owner. The hook is OR'd with the static feeless mappings,
+/// so it can only widen the feeless set, never shrink it.
+/// @dev `JBFeelessAddresses` invokes this hook inside a try/catch — a reverting hook is treated as returning `false`,
+/// so a broken hook cannot brick the fee path in terminals.
+interface IJBFeelessHook is IERC165 {
+    /// @notice Returns whether the address should be treated as feeless for the project.
+    /// @dev `caller` is the outer caller that triggered the fee-bearing terminal operation (as resolved by the
+    /// terminal's `_msgSender()`, so ERC-2771 meta-tx forwarders are unwrapped). It is `address(0)` when the registry
+    /// is queried without a caller hint (e.g. a direct off-chain `eth_call` to the registry). Use `caller` together
+    /// with `addr` to scope grants: e.g. an ecosystem router can be feeless ONLY when it is itself the entity calling
+    /// the terminal (so it gets fee-free cash-outs when zapping, but does NOT get feeless status when it merely
+    /// appears as a split recipient of someone else's payout).
+    /// @param projectId The ID of the project the fee would be charged on behalf of.
+    /// @param addr The address being checked (typically a payout recipient, surplus allowance beneficiary, or
+    /// cash-out beneficiary).
+    /// @param caller The outer caller that initiated the terminal operation, or `address(0)` if not provided.
+    /// @return A flag indicating whether the address is feeless for the project under the hook's custom logic.
+    function isFeeless(uint256 projectId, address addr, address caller) external view returns (bool);
+}

package/src/interfaces/IJBToken.sol

@@ -29,8 +29,8 @@ interface IJBToken {
     /// @notice Initializes the token with a name, symbol, and the JBTokens contract.
     /// @param name The token's name.
     /// @param symbol The token's symbol.
-    /// @param tokens The JBTokens contract that manages this token.
-    function initialize(string memory name, string memory symbol, address tokens) external;
+    /// @param tokensAddress The JBTokens contract that manages this token.
+    function initialize(string memory name, string memory symbol, address tokensAddress) external;
 
     /// @notice Mints tokens to an account.
     /// @param account The address to mint tokens to.

package/src/libraries/JBCashOuts.sol

@@ -42,7 +42,7 @@ library JBCashOuts {
         if (cashOutCount >= totalSupply) return surplus;
 
         // Get a reference to the linear proportion.
-        uint256 base = mulDiv(surplus, cashOutCount, totalSupply);
+        uint256 base = mulDiv({x: surplus, y: cashOutCount, denominator: totalSupply});
 
         // These conditions are all part of the same curve.
         // Edge conditions are separated to minimize the operations performed in those cases.
@@ -50,11 +50,12 @@ library JBCashOuts {
             return base;
         }
 
-        return mulDiv(
-            base,
-            (JBConstants.MAX_CASH_OUT_TAX_RATE - cashOutTaxRate) + mulDiv(cashOutTaxRate, cashOutCount, totalSupply),
-            JBConstants.MAX_CASH_OUT_TAX_RATE
-        );
+        return mulDiv({
+            x: base,
+            y: (JBConstants.MAX_CASH_OUT_TAX_RATE - cashOutTaxRate)
+                + mulDiv({x: cashOutTaxRate, y: cashOutCount, denominator: totalSupply}),
+            denominator: JBConstants.MAX_CASH_OUT_TAX_RATE
+        });
     }
 
     /// @notice Returns the minimum number of tokens that must be cashed out to receive at least `desiredOutput` of
@@ -93,9 +94,9 @@ library JBCashOuts {
 
         // Linear case (no tax): out = surplus * c / totalSupply, so c = ceil(out * totalSupply / surplus).
         if (cashOutTaxRate == 0) {
-            uint256 count = mulDiv(desiredOutput, totalSupply, surplus);
+            uint256 count = mulDiv({x: desiredOutput, y: totalSupply, denominator: surplus});
             // Round up if the floor division undershoots.
-            if (mulDiv(surplus, count, totalSupply) < desiredOutput) count++;
+            if (mulDiv({x: surplus, y: count, denominator: totalSupply}) < desiredOutput) count++;
             return count;
         }
 

package/src/libraries/JBFees.sol

@@ -15,7 +15,7 @@ library JBFees {
     /// @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 `amountBeforeFee`.
     function feeAmountFrom(uint256 amountBeforeFee, uint256 feePercent) internal pure returns (uint256) {
-        return mulDiv(amountBeforeFee, feePercent, JBConstants.MAX_FEE);
+        return mulDiv({x: amountBeforeFee, y: feePercent, denominator: JBConstants.MAX_FEE});
     }
 
     /// @notice Returns the fee amount that, when added to `amountAfterFee`, produces the gross amount needed to yield
@@ -25,7 +25,8 @@ library JBFees {
     /// @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 `amountAfterFee`.
     function feeAmountResultingIn(uint256 amountAfterFee, uint256 feePercent) internal pure returns (uint256) {
-        return mulDiv(amountAfterFee, JBConstants.MAX_FEE, JBConstants.MAX_FEE - feePercent) - amountAfterFee;
+        return mulDiv({x: amountAfterFee, y: JBConstants.MAX_FEE, denominator: JBConstants.MAX_FEE - feePercent})
+            - amountAfterFee;
     }
 
     /// @notice Returns the standard protocol fee taken from `amountBeforeFee`.
@@ -45,6 +46,6 @@ library JBFees {
     /// @return The fee amount that, when added to `amountAfterFee`, yields the gross pre-fee amount.
     function standardFeeAmountResultingIn(uint256 amountAfterFee) internal pure returns (uint256) {
         // Use `mulDiv` instead of `amountAfterFee * 40 / 39` to preserve overflow safety.
-        return mulDiv(amountAfterFee, 40, 39) - amountAfterFee;
+        return mulDiv({x: amountAfterFee, y: 40, denominator: 39}) - amountAfterFee;
     }
 }

package/src/libraries/JBMetadataResolver.sol

@@ -30,22 +30,15 @@ library JBMetadataResolver {
     error JBMetadataResolver_MetadataTooLong(uint256 offset, uint256 maxOffset);
     error JBMetadataResolver_MetadataTooShort(uint256 metadataLength, uint256 minMetadataLength);
 
-    // The various sizes used in bytes.
-    uint256 constant ID_SIZE = 4;
+    // Constants alphabetized per STYLE_GUIDE; trailing comments document derivation.
     uint256 constant ID_OFFSET_SIZE = 1;
+    uint256 constant ID_SIZE = 4;
+    uint256 constant MIN_METADATA_LENGTH = 37; // RESERVED_SIZE + ID_SIZE + ID_OFFSET_SIZE
+    uint256 constant NEXT_ID_OFFSET = 9; // TOTAL_ID_SIZE + ID_SIZE
+    uint256 constant RESERVED_SIZE = 32; // 1 * WORD_SIZE — protocol-reserved leading word
+    uint256 constant TOTAL_ID_SIZE = 5; // ID_SIZE + ID_OFFSET_SIZE
     uint256 constant WORD_SIZE = 32;
 
-    // The size that an ID takes in the lookup table (Identifier + Offset).
-    uint256 constant TOTAL_ID_SIZE = 5; // ID_SIZE + ID_OFFSET_SIZE;
-
-    // The amount of bytes to go forward to get to the offset of the next ID (aka. the end of the offset of the current
-    // ID).
-    uint256 constant NEXT_ID_OFFSET = 9; // TOTAL_ID_SIZE + ID_SIZE;
-
-    // 1 word (32B) is reserved for the protocol .
-    uint256 constant RESERVED_SIZE = 32; // 1 * WORD_SIZE;
-    uint256 constant MIN_METADATA_LENGTH = 37; // RESERVED_SIZE + ID_SIZE + ID_OFFSET_SIZE;
-
     /// @notice Add an {id: data} entry to an existing metadata. This is an append-only mechanism.
     /// @param originalMetadata The original metadata
     /// @param idToAdd The id to add

package/src/libraries/JBPayoutSplitGroupLib.sol

@@ -141,7 +141,7 @@ library JBPayoutSplitGroupLib {
         // refund = amount * (netPayoutAmount - sent) / netPayoutAmount. For full consumption this branch is
         // skipped. For zero consumption this refunds the full `amount` (i.e. the gross, fee allocation included).
         if (sent < netPayoutAmount) {
-            uint256 refund = mulDiv(amount, netPayoutAmount - sent, netPayoutAmount);
+            uint256 refund = mulDiv({x: amount, y: netPayoutAmount - sent, denominator: netPayoutAmount});
             if (refund != 0) {
                 store.recordAddedBalanceFor({projectId: projectId, token: token, amount: refund});
             }
@@ -151,7 +151,7 @@ library JBPayoutSplitGroupLib {
         // gross-equivalent of what the hook actually consumed so the held fee scales with consumption rather
         // than with the project's original payout intent.
         if (netPayoutAmount < amount && sent != 0) {
-            feeEligibleAmount = mulDiv(amount, sent, netPayoutAmount);
+            feeEligibleAmount = mulDiv({x: amount, y: sent, denominator: netPayoutAmount});
         }
     }
 
@@ -192,7 +192,7 @@ library JBPayoutSplitGroupLib {
             JBSplit memory split = payoutSplits[i];
 
             // The amount to send to the split.
-            uint256 payoutAmount = mulDiv(leftoverAmount, split.percent, leftoverPercentage);
+            uint256 payoutAmount = mulDiv({x: leftoverAmount, y: split.percent, denominator: leftoverPercentage});
 
             // Send the payout (inlined to keep stack pressure manageable with the tuple return).
             // Returns (netPayoutAmount sent, feeEligible gross-equivalent). For non-hook splits and fully-consumed

package/src/libraries/JBRulesetMetadataResolver.sol

@@ -8,6 +8,9 @@ import {JBRulesetMetadata} from "./../structs/JBRulesetMetadata.sol";
 /// encodes: reservedPercent, cashOutTaxRate, baseCurrency, 14 boolean flags (pausePay, allowOwnerMinting, etc.),
 /// a data hook address, and 14 bits of custom metadata. Used throughout the protocol to read ruleset configuration
 /// without storing each field separately.
+/// @dev Getter functions are intentionally laid out in bit-position order (low → high), not alphabetical, so that
+/// the source reads as a visual key for the bit layout written by `packRulesetMetadata`. This is the documented
+/// exception to STYLE_GUIDE function ordering for libraries.
 library JBRulesetMetadataResolver {
     function reservedPercent(JBRuleset memory ruleset) internal pure returns (uint16) {
         return uint16(ruleset.metadata >> 4);

package/src/structs/JBFundAccessLimitGroup.sol

@@ -4,6 +4,7 @@ pragma solidity ^0.8.0;
 import {JBCurrencyAmount} from "./JBCurrencyAmount.sol";
 
 /// @notice Defines how much a project can withdraw from a specific terminal and token each funding cycle.
+/// @dev A ruleset configuration should include at most one group for each `(terminal, token)` pair.
 /// @dev Example — payout limit of 5 USD in an ETH terminal: the project can distribute up to 5 USD worth of ETH to
 /// its splits per cycle. Example — surplus allowance of 5 USD: the project owner can pull up to 5 USD worth of ETH
 /// from the surplus (balance above payout limits).

package/test/helpers/JBTest.sol

@@ -37,6 +37,15 @@ contract JBTest is Test {
         vm.expectCall(_where, _encodedCall);
     }
 
+    /// @notice Calldata for `IJBFeelessAddresses.isFeelessFor(address,uint256,address)`.
+    /// @dev `isFeelessFor` is overloaded on the registry; `abi.encodeCall(IJBFeelessAddresses.isFeelessFor, ...)` is
+    /// ambiguous after the caller-aware overload was added. Terminals call the 3-arg variant forwarding
+    /// `_msgSender()`, so unit tests mocking the registry must encode the 3-arg selector with the expected caller.
+    function feelessCalldata(address addr, uint256 projectId, address caller) public pure returns (bytes memory) {
+        return
+            abi.encodeWithSelector(bytes4(keccak256("isFeelessFor(address,uint256,address)")), addr, projectId, caller);
+    }
+
     // Multiple calls with different return values
     function mockExpectSubsequent(address _where, bytes memory _encodedCall, bytes[] memory _returns) public {
         // Mocks calls with different return values

package/test/mock/MockFeelessHook.sol

@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.28;
+
+import {IJBFeelessHook} from "../../src/interfaces/IJBFeelessHook.sol";
+
+import {ERC165, IERC165} from "@openzeppelin/contracts/utils/introspection/ERC165.sol";
+
+/// @notice Configurable `IJBFeelessHook` mock for unit tests.
+/// @dev `mode` controls behavior of `isFeeless`:
+///   - 0: returns `defaultResult` for any (projectId, addr)
+///   - 1: reverts with `Nope()`
+///   - 2: reverts via `require(false, "nope")`
+///   - 3: returns `true` iff `(projectId, addr)` has been allowlisted via `setAllowed`
+contract MockFeelessHook is ERC165, IJBFeelessHook {
+    error Nope();
+
+    uint256 public mode;
+    bool public defaultResult;
+    mapping(uint256 => mapping(address => bool)) internal _allowed;
+
+    function setMode(uint256 newMode) external {
+        mode = newMode;
+    }
+
+    function setDefaultResult(bool result) external {
+        defaultResult = result;
+    }
+
+    function setAllowed(uint256 projectId, address addr, bool flag) external {
+        _allowed[projectId][addr] = flag;
+    }
+
+    function isFeeless(uint256 projectId, address addr, address) external view override returns (bool) {
+        if (mode == 1) revert Nope();
+        if (mode == 2) require(false, "nope");
+        if (mode == 3) return _allowed[projectId][addr];
+        return defaultResult;
+    }
+
+    function supportsInterface(bytes4 interfaceId) public view override(IERC165, ERC165) returns (bool) {
+        return interfaceId == type(IJBFeelessHook).interfaceId || super.supportsInterface(interfaceId);
+    }
+}
+
+/// @notice Non-conforming "hook" that returns false for the IJBFeelessHook interfaceId in ERC-165.
+/// @dev Used to test the `setFeelessHook` validation guard. Has the `isFeeless` selector so the
+/// call shape matches, but its `supportsInterface` advertises only IERC165, not IJBFeelessHook.
+contract MockNonConformingFeelessHook is ERC165 {
+    function isFeeless(uint256, address, address) external pure returns (bool) {
+        return true;
+    }
+}
+
+/// @notice "Hook" with no `supportsInterface` at all — `setFeelessHook` should revert when this is passed.
+contract MockEoaLikeFeelessHook {
+    function isFeeless(uint256, address, address) external pure returns (bool) {
+        return true;
+    }
+}