@bananapus/721-hook-v6 0.0.51 → 0.0.52

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/721-hook-v6",
-  "version": "0.0.51",
+  "version": "0.0.52",
   "license": "MIT",
   "repository": {
     "type": "git",

package/script/Deploy.s.sol

@@ -24,20 +24,14 @@ contract DeployScript is Script, Sphinx {
     AddressRegistryDeployment registry;
 
     /// @notice The address that is allowed to forward calls to the terminal and controller on a users behalf.
-    // forge-lint: disable-next-line(mixed-case-variable)
-    address private TRUSTED_FORWARDER;
+    address private trustedForwarder;
 
     /// @notice the salts that are used to deploy the contracts.
-    // forge-lint: disable-next-line(mixed-case-variable)
-    bytes32 HOOK_SALT = "JB721TiersHookV6_";
-    // forge-lint: disable-next-line(mixed-case-variable)
-    bytes32 HOOK_DEPLOYER_SALT = "JB721TiersHookDeployerV6_";
-    // forge-lint: disable-next-line(mixed-case-variable)
-    bytes32 HOOK_STORE_SALT = "JB721TiersHookStoreV6_";
-    // forge-lint: disable-next-line(mixed-case-variable)
-    bytes32 PROJECT_DEPLOYER_SALT = "JB721TiersHookProjectDeployerV6";
-    // forge-lint: disable-next-line(mixed-case-variable)
-    bytes32 CHECKPOINTS_DEPLOYER_SALT = "JB721CheckpointsDeployerV6";
+    bytes32 private constant _HOOK_SALT = "JB721TiersHookV6_";
+    bytes32 private constant _HOOK_DEPLOYER_SALT = "JB721TiersHookDeployerV6_";
+    bytes32 private constant _HOOK_STORE_SALT = "JB721TiersHookStoreV6_";
+    bytes32 private constant _PROJECT_DEPLOYER_SALT = "JB721TiersHookProjectDeployerV6";
+    bytes32 private constant _CHECKPOINTS_DEPLOYER_SALT = "JB721CheckpointsDeployerV6";
 
     function configureSphinx() public override {
         sphinxConfig.projectName = "nana-721-hook-v6";
@@ -53,7 +47,7 @@ contract DeployScript is Script, Sphinx {
         );
 
         // We use the same trusted forwarder as the core deployment.
-        TRUSTED_FORWARDER = core.permissions.trustedForwarder();
+        trustedForwarder = core.permissions.trustedForwarder();
 
         registry = AddressRegistryDeploymentLib.getDeployment(
             vm.envOr(
@@ -74,25 +68,25 @@ contract DeployScript is Script, Sphinx {
         {
             // Perform the check for the store.
             (address _store, bool _storeIsDeployed) = _isDeployed({
-                salt: HOOK_STORE_SALT, creationCode: type(JB721TiersHookStore).creationCode, arguments: ""
+                salt: _HOOK_STORE_SALT, creationCode: type(JB721TiersHookStore).creationCode, arguments: ""
             });
 
             // Deploy it if it has not been deployed yet.
-            store = !_storeIsDeployed ? new JB721TiersHookStore{salt: HOOK_STORE_SALT}() : JB721TiersHookStore(_store);
+            store = !_storeIsDeployed ? new JB721TiersHookStore{salt: _HOOK_STORE_SALT}() : JB721TiersHookStore(_store);
         }
 
         JB721CheckpointsDeployer checkpointsDeployer;
         {
             // Perform the check for the deployer.
             (address _deployer, bool _deployerIsDeployed) = _isDeployed({
-                salt: CHECKPOINTS_DEPLOYER_SALT,
+                salt: _CHECKPOINTS_DEPLOYER_SALT,
                 creationCode: type(JB721CheckpointsDeployer).creationCode,
                 arguments: abi.encode(store)
             });
 
             // Deploy it if it has not been deployed yet.
             checkpointsDeployer = !_deployerIsDeployed
-                ? new JB721CheckpointsDeployer{salt: CHECKPOINTS_DEPLOYER_SALT}(store)
+                ? new JB721CheckpointsDeployer{salt: _CHECKPOINTS_DEPLOYER_SALT}(store)
                 : JB721CheckpointsDeployer(_deployer);
         }
 
@@ -100,7 +94,7 @@ contract DeployScript is Script, Sphinx {
         {
             // Perform the check for the registry.
             (address _hook, bool _hookIsDeployed) = _isDeployed({
-                salt: HOOK_SALT,
+                salt: _HOOK_SALT,
                 creationCode: type(JB721TiersHook).creationCode,
                 arguments: abi.encode(
                     core.directory,
@@ -110,22 +104,22 @@ contract DeployScript is Script, Sphinx {
                     store,
                     core.splits,
                     checkpointsDeployer,
-                    TRUSTED_FORWARDER
+                    trustedForwarder
                 )
             });
 
             // Deploy it if it has not been deployed yet.
             hook = !_hookIsDeployed
-                ? new JB721TiersHook{salt: HOOK_SALT}(
-                    core.directory,
-                    core.permissions,
-                    core.prices,
-                    core.rulesets,
-                    store,
-                    core.splits,
-                    IJB721CheckpointsDeployer(address(checkpointsDeployer)),
-                    TRUSTED_FORWARDER
-                )
+                ? new JB721TiersHook{salt: _HOOK_SALT}({
+                    directory: core.directory,
+                    permissions: core.permissions,
+                    prices: core.prices,
+                    rulesets: core.rulesets,
+                    store: store,
+                    splits: core.splits,
+                    checkpointsDeployer: IJB721CheckpointsDeployer(address(checkpointsDeployer)),
+                    trustedForwarder: trustedForwarder
+                })
                 : JB721TiersHook(_hook);
         }
 
@@ -133,15 +127,15 @@ contract DeployScript is Script, Sphinx {
         {
             // Perform the check for the registry.
             (address _hookDeployer, bool _hookDeployerIsDeployed) = _isDeployed({
-                salt: HOOK_DEPLOYER_SALT,
+                salt: _HOOK_DEPLOYER_SALT,
                 creationCode: type(JB721TiersHookDeployer).creationCode,
-                arguments: abi.encode(hook, store, registry.registry, TRUSTED_FORWARDER)
+                arguments: abi.encode(hook, store, registry.registry, trustedForwarder)
             });
 
             hookDeployer = !_hookDeployerIsDeployed
-                ? new JB721TiersHookDeployer{salt: HOOK_DEPLOYER_SALT}(
-                    hook, store, registry.registry, TRUSTED_FORWARDER
-                )
+                ? new JB721TiersHookDeployer{salt: _HOOK_DEPLOYER_SALT}({
+                    hook: hook, store: store, addressRegistry: registry.registry, trustedForwarder: trustedForwarder
+                })
                 : JB721TiersHookDeployer(_hookDeployer);
         }
 
@@ -149,15 +143,18 @@ contract DeployScript is Script, Sphinx {
         {
             // Perform the check for the registry.
             (address _projectDeployer, bool _projectDeployerIsdeployed) = _isDeployed({
-                salt: PROJECT_DEPLOYER_SALT,
+                salt: _PROJECT_DEPLOYER_SALT,
                 creationCode: type(JB721TiersHookProjectDeployer).creationCode,
-                arguments: abi.encode(core.directory, core.permissions, hookDeployer, TRUSTED_FORWARDER)
+                arguments: abi.encode(core.directory, core.permissions, hookDeployer, trustedForwarder)
             });
 
             projectDeployer = !_projectDeployerIsdeployed
-                ? new JB721TiersHookProjectDeployer{salt: PROJECT_DEPLOYER_SALT}(
-                    core.directory, core.permissions, hookDeployer, TRUSTED_FORWARDER
-                )
+                ? new JB721TiersHookProjectDeployer{salt: _PROJECT_DEPLOYER_SALT}({
+                    directory: core.directory,
+                    permissions: core.permissions,
+                    hookDeployer: hookDeployer,
+                    trustedForwarder: trustedForwarder
+                })
                 : JB721TiersHookProjectDeployer(_projectDeployer);
         }
     }

package/script/helpers/Hook721DeploymentLib.sol

@@ -11,10 +11,8 @@ import {IJB721TiersHookProjectDeployer} from "../../src/interfaces/IJB721TiersHo
 import {IJB721TiersHookStore} from "../../src/interfaces/IJB721TiersHookStore.sol";
 
 struct Hook721Deployment {
-    // forge-lint: disable-next-line(mixed-case-variable)
-    IJB721TiersHookDeployer hook_deployer;
-    // forge-lint: disable-next-line(mixed-case-variable)
-    IJB721TiersHookProjectDeployer project_deployer;
+    IJB721TiersHookDeployer hookDeployer;
+    IJB721TiersHookProjectDeployer projectDeployer;
     IJB721TiersHookStore store;
 }
 
@@ -25,17 +23,16 @@ library Hook721DeploymentLib {
     Vm internal constant vm = Vm(VM_ADDRESS);
 
     function getDeployment(string memory path) internal returns (Hook721Deployment 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();
 
         for (uint256 _i; _i < networks.length; _i++) {
             if (networks[_i].chainId == chainId) {
-                return getDeployment({path: path, network_name: networks[_i].name});
+                return getDeployment({path: path, networkName: networks[_i].name});
             }
         }
 
@@ -44,27 +41,26 @@ library Hook721DeploymentLib {
 
     function getDeployment(
         string memory path,
-        // forge-lint: disable-next-line(mixed-case-variable)
-        string memory network_name
+        string memory networkName
     )
         internal
         view
         returns (Hook721Deployment memory deployment)
     {
-        deployment.hook_deployer = IJB721TiersHookDeployer(
+        deployment.hookDeployer = IJB721TiersHookDeployer(
             _getDeploymentAddress({
                 path: path,
-                project_name: "nana-721-hook-v6",
-                network_name: network_name,
+                projectName: "nana-721-hook-v6",
+                networkName: networkName,
                 contractName: "JB721TiersHookDeployer"
             })
         );
 
-        deployment.project_deployer = IJB721TiersHookProjectDeployer(
+        deployment.projectDeployer = IJB721TiersHookProjectDeployer(
             _getDeploymentAddress({
                 path: path,
-                project_name: "nana-721-hook-v6",
-                network_name: network_name,
+                projectName: "nana-721-hook-v6",
+                networkName: networkName,
                 contractName: "JB721TiersHookProjectDeployer"
             })
         );
@@ -72,8 +68,8 @@ library Hook721DeploymentLib {
         deployment.store = IJB721TiersHookStore(
             _getDeploymentAddress({
                 path: path,
-                project_name: "nana-721-hook-v6",
-                network_name: network_name,
+                projectName: "nana-721-hook-v6",
+                networkName: networkName,
                 contractName: "JB721TiersHookStore"
             })
         );
@@ -86,10 +82,8 @@ library Hook721DeploymentLib {
     /// @return The address of the contract.
     function _getDeploymentAddress(
         string memory path,
-        // forge-lint: disable-next-line(mixed-case-variable)
-        string memory project_name,
-        // forge-lint: disable-next-line(mixed-case-variable)
-        string memory network_name,
+        string memory projectName,
+        string memory networkName,
         string memory contractName
     )
         internal
@@ -98,7 +92,7 @@ library Hook721DeploymentLib {
     {
         string memory deploymentJson =
         // forge-lint: disable-next-line(unsafe-cheatcode)
-        vm.readFile(string.concat(path, project_name, "/", network_name, "/", contractName, ".json"));
-        return stdJson.readAddress(deploymentJson, ".address");
+        vm.readFile(string.concat(path, projectName, "/", networkName, "/", contractName, ".json"));
+        return stdJson.readAddress({json: deploymentJson, key: ".address"});
     }
 }

package/src/JB721Checkpoints.sol

@@ -40,7 +40,7 @@ contract JB721Checkpoints is Votes, IJB721Checkpoints {
     //*********************************************************************//
 
     /// @notice The hook that this module tracks voting power for.
-    address public override HOOK;
+    address public override hook;
 
     //*********************************************************************//
     // -------------------- internal stored properties ------------------- //
@@ -59,7 +59,7 @@ contract JB721Checkpoints is Votes, IJB721Checkpoints {
     /// @param store The store that holds tier data for each hook's NFTs.
     constructor(IJB721TiersHookStore store) EIP712("JB721Checkpoints", "1") {
         STORE = store;
-        HOOK = address(1);
+        hook = address(1);
     }
 
     //*********************************************************************//
@@ -81,7 +81,7 @@ contract JB721Checkpoints is Votes, IJB721Checkpoints {
             uint256 tokenId = tokenIds[i];
 
             // Only the current owner can enroll their tokens.
-            if (IERC721(HOOK).ownerOf(tokenId) != msg.sender) {
+            if (IERC721(hook).ownerOf(tokenId) != msg.sender) {
                 revert JB721Checkpoints_NotOwner({tokenId: tokenId, caller: msg.sender});
             }
 
@@ -99,20 +99,20 @@ contract JB721Checkpoints is Votes, IJB721Checkpoints {
 
     /// @notice Initializes a cloned module with its hook reference.
     /// @dev Can only be called once. Called by the deployer after cloning.
-    /// @param hook The hook this module serves.
-    function initialize(address hook) external override {
-        if (HOOK != address(0)) revert JB721Checkpoints_AlreadyInitialized({hook: HOOK});
+    /// @param hookAddress The hook this module serves.
+    function initialize(address hookAddress) external override {
+        if (hook != address(0)) revert JB721Checkpoints_AlreadyInitialized({hook: hook});
         // `hook` cannot be zero when called through the deployer because `msg.sender` must equal `hook`.
-        HOOK = hook;
+        hook = hookAddress;
     }
 
     /// @notice Called by the hook after every NFT transfer to update checkpointed voting power.
-    /// @dev Only callable by the HOOK. Looks up the token's tier voting units from the store.
+    /// @dev Only callable by the hook. Looks up the token's tier voting units from the store.
     /// @param from The previous owner (address(0) on mint).
     /// @param to The new owner (address(0) on burn).
     /// @param tokenId The token ID to transfer.
     function onTransfer(address from, address to, uint256 tokenId) external override {
-        if (msg.sender != HOOK) revert JB721Checkpoints_Unauthorized({caller: msg.sender, hook: HOOK});
+        if (msg.sender != hook) revert JB721Checkpoints_Unauthorized({caller: msg.sender, hook: hook});
 
         if (from != address(0)) {
             // forge-lint: disable-next-line(unsafe-typecast)
@@ -120,7 +120,7 @@ contract JB721Checkpoints is Votes, IJB721Checkpoints {
         }
 
         // Look up this token's tier to get its voting units.
-        uint256 votingUnits = STORE.tierOfTokenId({hook: HOOK, tokenId: tokenId, includeResolvedUri: false}).votingUnits;
+        uint256 votingUnits = STORE.tierOfTokenId({hook: hook, tokenId: tokenId, includeResolvedUri: false}).votingUnits;
 
         // Move checkpointed voting power from the previous owner to the new owner.
         _transferVotingUnits({from: from, to: to, amount: votingUnits});
@@ -161,6 +161,6 @@ contract JB721Checkpoints is Votes, IJB721Checkpoints {
     /// @param account The address to get the voting units of.
     /// @return The total voting units the account holds.
     function _getVotingUnits(address account) internal view override returns (uint256) {
-        return STORE.votingUnitsOf({hook: HOOK, account: account});
+        return STORE.votingUnitsOf({hook: hook, account: account});
     }
 }

package/src/JB721TiersHook.sol

@@ -107,7 +107,7 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
 
     /// @notice The checkpoint module that manages IVotes-compatible checkpointed voting power for this hook's NFTs.
     /// @dev Lazily deployed on the first transfer. Pass this to JBTokenDistributor as the IVotes token.
-    IJB721Checkpoints public override CHECKPOINTS;
+    IJB721Checkpoints public override checkpoints;
 
     //*********************************************************************//
     // -------------------------- constructor ---------------------------- //
@@ -232,9 +232,9 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
     /// @notice Initialize a cloned copy of the hook. Sets the project association, ERC-721 name/symbol, pricing
     /// context (currency + decimals), metadata URIs, initial tiers, and behavioral flags. Can only be called once
     /// per clone — the implementation contract is pre-initialized in its constructor to prevent misuse.
-    /// @dev Called by `JB721TiersHookDeployer` immediately after cloning. Reverts with
-    /// `JB721TiersHook_AlreadyInitialized` if called more than once, or `JB721TiersHook_NoProjectId` if projectId is 0.
-    /// @param projectId The ID of the project this hook is associated with.
+    /// @dev Called by `JB721TiersHookDeployer` immediately after cloning. Reverts if called more than once or if the
+    /// project ID is zero.
+    /// @param initialProjectId The ID of the project this hook is associated with.
     /// @param name The name of the NFT collection.
     /// @param symbol The symbol representing the NFT collection.
     /// @param baseUri The URI to use as a base for full NFT `tokenUri`s.
@@ -244,7 +244,7 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
     /// category (from least to greatest).
     /// @param flags A set of additional options which dictate how the hook behaves.
     function initialize(
-        uint256 projectId,
+        uint256 initialProjectId,
         string memory name,
         string memory symbol,
         string memory baseUri,
@@ -258,14 +258,14 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
     {
         // Stop re-initialization. This protects both the implementation contract (initialized in constructor)
         // and clones (initialized via this function).
-        if (_initialized) revert JB721TiersHook_AlreadyInitialized(PROJECT_ID);
+        if (_initialized) revert JB721TiersHook_AlreadyInitialized({projectId: projectId});
         _initialized = true;
 
-        // Make sure a projectId is provided.
-        if (projectId == 0) revert JB721TiersHook_NoProjectId({projectId: projectId});
+        // Make sure a project ID is provided.
+        if (initialProjectId == 0) revert JB721TiersHook_NoProjectId({projectId: initialProjectId});
 
         // Initialize the superclass.
-        JB721Hook._initialize({projectId: projectId, name: name, symbol: symbol});
+        JB721Hook._initialize({initialProjectId: initialProjectId, name: name, symbol: symbol});
 
         // Validate pricing decimals are within a reasonable range.
         if (tiersConfig.decimals > 18) revert JB721TiersHook_InvalidPricingDecimals(tiersConfig.decimals);
@@ -326,7 +326,8 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
     /// @return The token URI from the `tokenUriResolver` if it is set. If it isn't set, the token URI for the NFT's
     /// tier.
     function tokenURI(uint256 tokenId) public view virtual override returns (string memory) {
-        return JB721TiersHookLib.resolveTokenURI(STORE, address(this), baseURI, tokenId);
+        return
+            JB721TiersHookLib.resolveTokenURI({store: STORE, hook: address(this), baseUri: baseURI, tokenId: tokenId});
     }
 
     /// @notice The total cash-out weight across all outstanding NFTs and pending reserves. This is the denominator
@@ -348,15 +349,13 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
     /// @param tierIdsToRemove The IDs of the tiers to remove.
     function adjustTiers(JB721TierConfig[] calldata tiersToAdd, uint256[] calldata tierIdsToRemove) external override {
         // Enforce permissions.
-        _requirePermissionFrom({
-            account: owner(), projectId: PROJECT_ID, permissionId: JBPermissionIds.ADJUST_721_TIERS
-        });
+        _requirePermissionFrom({account: owner(), projectId: projectId, permissionId: JBPermissionIds.ADJUST_721_TIERS});
 
         // Delegate to the library (via DELEGATECALL) for tier removal, addition, event emission, and split setting.
         JB721TiersHookLib.adjustTiersFor({
             store: STORE,
             splits: SPLITS,
-            projectId: PROJECT_ID,
+            projectId: projectId,
             hookAddress: address(this),
             caller: _msgSender(),
             tiersToAdd: tiersToAdd,
@@ -379,7 +378,7 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
         returns (uint256[] memory tokenIds)
     {
         // Enforce permissions.
-        _requirePermissionFrom({account: owner(), projectId: PROJECT_ID, permissionId: JBPermissionIds.MINT_721});
+        _requirePermissionFrom({account: owner(), projectId: projectId, permissionId: JBPermissionIds.MINT_721});
 
         // Record the mint. The token IDs returned correspond to the tiers passed in.
         (tokenIds,,) = STORE.recordMint({
@@ -417,7 +416,7 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
     function setDiscountPercentOf(uint256 tierId, uint256 discountPercent) external override {
         // Enforce permissions.
         _requirePermissionFrom({
-            account: owner(), projectId: PROJECT_ID, permissionId: JBPermissionIds.SET_721_DISCOUNT_PERCENT
+            account: owner(), projectId: projectId, permissionId: JBPermissionIds.SET_721_DISCOUNT_PERCENT
         });
         _setDiscountPercentOf({tierId: tierId, discountPercent: discountPercent});
     }
@@ -428,7 +427,7 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
     function setDiscountPercentsOf(JB721TiersSetDiscountPercentConfig[] calldata configs) external override {
         // Enforce permissions.
         _requirePermissionFrom({
-            account: owner(), projectId: PROJECT_ID, permissionId: JBPermissionIds.SET_721_DISCOUNT_PERCENT
+            account: owner(), projectId: projectId, permissionId: JBPermissionIds.SET_721_DISCOUNT_PERCENT
         });
 
         for (uint256 i; i < configs.length;) {
@@ -453,24 +452,22 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
     /// @param tokenUriResolver The new URI resolver. Pass `IJB721TokenUriResolver(address(this))` as a sentinel value
     /// to leave unchanged. `address(this)` is used instead of `address(0)` because `address(0)` is a valid value that
     /// clears the resolver.
-    /// @param encodedIPFSUriTierId The ID of the tier to set the encoded IPFS URI of.
-    /// @param encodedIPFSUri The encoded IPFS URI to set.
+    /// @param encodedIpfsUriTierId The ID of the tier to set the encoded IPFS URI of.
+    /// @param encodedIpfsUri The encoded IPFS URI to set.
     function setMetadata(
         string calldata name,
         string calldata symbol,
         string calldata baseUri,
         string calldata contractUri,
         IJB721TokenUriResolver tokenUriResolver,
-        uint256 encodedIPFSUriTierId,
-        bytes32 encodedIPFSUri
+        uint256 encodedIpfsUriTierId,
+        bytes32 encodedIpfsUri
     )
         external
         override
     {
         // Enforce permissions.
-        _requirePermissionFrom({
-            account: owner(), projectId: PROJECT_ID, permissionId: JBPermissionIds.SET_721_METADATA
-        });
+        _requirePermissionFrom({account: owner(), projectId: projectId, permissionId: JBPermissionIds.SET_721_METADATA});
 
         // Cache _msgSender() at function entry to avoid repeated calls.
         address caller = _msgSender();
@@ -501,11 +498,11 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
             // Store the new URI resolver.
             _recordSetTokenUriResolver(tokenUriResolver);
         }
-        if (encodedIPFSUriTierId != 0 && encodedIPFSUri != bytes32(0)) {
-            emit SetEncodedIPFSUri({tierId: encodedIPFSUriTierId, encodedUri: encodedIPFSUri, caller: caller});
+        if (encodedIpfsUriTierId != 0 && encodedIpfsUri != bytes32(0)) {
+            emit SetEncodedIpfsUri({tierId: encodedIpfsUriTierId, encodedUri: encodedIpfsUri, caller: caller});
 
             // Store the new encoded IPFS URI.
-            STORE.recordSetEncodedIPFSUriOf({tierId: encodedIPFSUriTierId, encodedIPFSUri: encodedIPFSUri});
+            STORE.recordSetEncodedIpfsUriOf({tierId: encodedIpfsUriTierId, encodedIpfsUri: encodedIpfsUri});
         }
     }
 
@@ -519,12 +516,12 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
     /// @param count The number of reserved NFTs to mint.
     function mintPendingReservesFor(uint256 tierId, uint256 count) public override {
         // Get a reference to the project's current ruleset.
-        JBRuleset memory ruleset = _currentRulesetOf(PROJECT_ID);
+        JBRuleset memory ruleset = _currentRulesetOf(projectId);
 
         // Pending reserve mints must not be paused.
         if (JB721TiersRulesetMetadataResolver.mintPendingReservesPaused((JBRulesetMetadataResolver.metadata(ruleset))))
         {
-            revert JB721TiersHook_MintReserveNftsPaused({projectId: PROJECT_ID, tierId: tierId});
+            revert JB721TiersHook_MintReserveNftsPaused({projectId: projectId, tierId: tierId});
         }
 
         // Record the reserved mint for the tier.
@@ -694,7 +691,7 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
         (value, valid) = JB721TiersHookLib.normalizePaymentValue({
             packedPricingContext: _packedPricingContext,
             prices: PRICES,
-            projectId: PROJECT_ID,
+            projectId: projectId,
             amountValue: context.amount.value,
             amountCurrency: context.amount.currency,
             amountDecimals: context.amount.decimals
@@ -722,7 +719,7 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
             JB721TiersHookLib.distributeAll({
                 directory: DIRECTORY,
                 splits: SPLITS,
-                projectId: PROJECT_ID,
+                projectId: projectId,
                 hookAddress: address(this),
                 token: context.forwardedAmount.token,
                 amount: context.forwardedAmount.value,
@@ -766,7 +763,7 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
             // If transfers are pausable, check if they're paused.
             if (transfersPausable) {
                 // Get a reference to the project's current ruleset.
-                JBRuleset memory ruleset = _currentRulesetOf(PROJECT_ID);
+                JBRuleset memory ruleset = _currentRulesetOf(projectId);
 
                 // If transfers are paused and the NFT isn't being transferred to the zero address, revert.
                 if (
@@ -776,7 +773,7 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
                         )
                 ) {
                     revert JB721TiersHook_TierTransfersPaused({
-                        projectId: PROJECT_ID, tokenId: tokenId, from: from, to: to
+                        projectId: projectId, tokenId: tokenId, from: from, to: to
                     });
                 }
             }
@@ -789,11 +786,11 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
         STORE.recordTransferForTier({tierId: tierId, from: from, to: to});
 
         // Deploy the checkpoint module lazily on the first transfer.
-        if (address(CHECKPOINTS) == address(0)) {
-            CHECKPOINTS = CHECKPOINTS_DEPLOYER.deploy(address(this));
+        if (address(checkpoints) == address(0)) {
+            checkpoints = CHECKPOINTS_DEPLOYER.deploy(address(this));
         }
 
         // Notify the checkpoint module to update checkpointed voting power.
-        CHECKPOINTS.onTransfer({from: from, to: to, tokenId: tokenId});
+        checkpoints.onTransfer({from: from, to: to, tokenId: tokenId});
     }
 }

package/src/JB721TiersHookDeployer.sol

@@ -89,7 +89,7 @@ contract JB721TiersHookDeployer is ERC2771Context, IJB721TiersHookDeployer {
         emit HookDeployed({projectId: projectId, hook: newHook, caller: _msgSender()});
 
         newHook.initialize({
-            projectId: projectId,
+            initialProjectId: projectId,
             name: deployTiersHookConfig.name,
             symbol: deployTiersHookConfig.symbol,
             baseUri: deployTiersHookConfig.baseUri,

package/src/JB721TiersHookProjectDeployer.sol

@@ -89,8 +89,8 @@ contract JB721TiersHookProjectDeployer is
         returns (uint256 projectId, IJB721TiersHook hook)
     {
         // Reserve the project ID up front so permissionless project creations cannot invalidate hook deployment.
-        IJBProjects PROJECTS = DIRECTORY.PROJECTS();
-        projectId = PROJECTS.createFor(address(this));
+        IJBProjects projects = DIRECTORY.PROJECTS();
+        projectId = projects.createFor(address(this));
 
         // Deploy the hook.
         hook = HOOK_DEPLOYER.deployHookFor({
@@ -108,7 +108,7 @@ contract JB721TiersHookProjectDeployer is
         JBOwnable(address(hook)).transferOwnershipToProject(projectId);
 
         // Transfer the project NFT to its intended owner.
-        PROJECTS.safeTransferFrom({from: address(this), to: owner, tokenId: projectId});
+        projects.safeTransferFrom({from: address(this), to: owner, tokenId: projectId});
     }
 
     /// @notice Launches rulesets for a project with an attached 721 tiers hook.
@@ -135,8 +135,8 @@ contract JB721TiersHookProjectDeployer is
         returns (uint256 rulesetId, IJB721TiersHook hook)
     {
         // Get the project's projects contract.
-        IJBProjects PROJECTS = DIRECTORY.PROJECTS();
-        address projectOwner = PROJECTS.ownerOf(projectId);
+        IJBProjects projects = DIRECTORY.PROJECTS();
+        address projectOwner = projects.ownerOf(projectId);
 
         // Enforce permissions.
         _requirePermissionFrom({

package/src/JB721TiersHookStore.sol

@@ -71,7 +71,7 @@ contract JB721TiersHookStore is IJB721TiersHookStore {
     /// @custom:param hook The 721 contract that the tier belongs to.
     /// @custom:param tierId The ID of the tier to get the encoded IPFS URI of.
     /// @custom:returns The encoded IPFS URI.
-    mapping(address hook => mapping(uint256 tierId => bytes32)) public override encodedIPFSUriOf;
+    mapping(address hook => mapping(uint256 tierId => bytes32)) public override encodedIpfsUriOf;
 
     /// @notice Returns the largest tier ID currently used on the provided 721 contract.
     /// @dev This may not include the last tier ID if it has been removed.
@@ -166,7 +166,7 @@ contract JB721TiersHookStore is IJB721TiersHookStore {
     /// @return The encoded IPFS URI for the NFT's tier.
     // forge-lint: disable-next-line(mixed-case-function)
     function encodedTierIPFSUriOf(address hook, uint256 tokenId) external view override returns (bytes32) {
-        return encodedIPFSUriOf[hook][tierIdOfToken(tokenId)];
+        return encodedIpfsUriOf[hook][tierIdOfToken(tokenId)];
     }
 
     /// @notice Get the behavioral flags for a hook — such as whether transfers are pausable, whether NFT holders can
@@ -628,7 +628,7 @@ contract JB721TiersHookStore is IJB721TiersHookStore {
             // No reserve frequency if there is no reserve beneficiary.
             reserveFrequency: reserveBeneficiary == address(0) ? 0 : storedTier.reserveFrequency,
             reserveBeneficiary: reserveBeneficiary,
-            encodedIPFSUri: encodedIPFSUriOf[hook][tierId],
+            encodedIpfsUri: encodedIpfsUriOf[hook][tierId],
             category: storedTier.category,
             discountPercent: storedTier.discountPercent,
             flags: JB721TierFlags({
@@ -1051,9 +1051,9 @@ contract JB721TiersHookStore is IJB721TiersHookStore {
                 }
             }
 
-            // Set the `encodedIPFSUri` if needed.
-            if (tierToAdd.encodedIPFSUri != bytes32(0)) {
-                encodedIPFSUriOf[msg.sender][tierId] = tierToAdd.encodedIPFSUri;
+            // Set the `encodedIpfsUri` if needed.
+            if (tierToAdd.encodedIpfsUri != bytes32(0)) {
+                encodedIpfsUriOf[msg.sender][tierId] = tierToAdd.encodedIpfsUri;
             }
 
             if (startSortedTierId != 0) {
@@ -1392,10 +1392,10 @@ contract JB721TiersHookStore is IJB721TiersHookStore {
 
     /// @notice Record a new encoded IPFS URI for a tier.
     /// @param tierId The ID of the tier to set the encoded IPFS URI of.
-    /// @param encodedIPFSUri The encoded IPFS URI to set for the tier.
+    /// @param encodedIpfsUri The encoded IPFS URI to set for the tier.
     // forge-lint: disable-next-line(mixed-case-function)
-    function recordSetEncodedIPFSUriOf(uint256 tierId, bytes32 encodedIPFSUri) external override {
-        encodedIPFSUriOf[msg.sender][tierId] = encodedIPFSUri;
+    function recordSetEncodedIpfsUriOf(uint256 tierId, bytes32 encodedIpfsUri) external override {
+        encodedIpfsUriOf[msg.sender][tierId] = encodedIpfsUri;
     }
 
     /// @notice Record a newly set token URI resolver.

package/src/abstract/ERC721.sol

@@ -40,9 +40,9 @@ abstract contract ERC721 is Context, ERC165, IERC721, IERC721Metadata, IERC721Er
     /**
      * @dev Initializes the contract by setting a `name` and a `symbol` to the token collection.
      */
-    function _initialize(string memory name_, string memory symbol_) internal {
-        _name = name_;
-        _symbol = symbol_;
+    function _initialize(string memory collectionName, string memory collectionSymbol) internal {
+        _name = collectionName;
+        _symbol = collectionSymbol;
     }
 
     /**

package/src/abstract/JB721Hook.sol

@@ -50,7 +50,7 @@ abstract contract JB721Hook is ERC721, IJB721Hook {
     //*********************************************************************//
 
     /// @notice The ID of the project that this contract is associated with.
-    uint256 public override PROJECT_ID;
+    uint256 public override projectId;
 
     //*********************************************************************//
     // -------------------------- constructor ---------------------------- //
@@ -194,16 +194,16 @@ abstract contract JB721Hook is ERC721, IJB721Hook {
         override
     {
         // Keep a reference to the project ID.
-        uint256 projectId = PROJECT_ID;
+        uint256 localProjectId = projectId;
 
         // Make sure the caller is a terminal of the project, and that the call is being made on behalf of an
         // interaction with the correct project.
         if (
-            msg.value != 0 || !DIRECTORY.isTerminalOf({projectId: projectId, terminal: IJBTerminal(msg.sender)})
-                || context.projectId != projectId
+            msg.value != 0 || !DIRECTORY.isTerminalOf({projectId: localProjectId, terminal: IJBTerminal(msg.sender)})
+                || context.projectId != localProjectId
         ) {
             revert JB721Hook_InvalidCashOut({
-                caller: msg.sender, contextProjectId: context.projectId, projectId: projectId, msgValue: msg.value
+                caller: msg.sender, contextProjectId: context.projectId, projectId: localProjectId, msgValue: msg.value
             });
         }
 
@@ -243,15 +243,17 @@ abstract contract JB721Hook is ERC721, IJB721Hook {
     /// @dev Reverts if the calling contract is not one of the project's terminals.
     /// @param context The payment context passed in by the terminal.
     function afterPayRecordedWith(JBAfterPayRecordedContext calldata context) external payable virtual override {
-        uint256 projectId = PROJECT_ID;
+        uint256 localProjectId = projectId;
 
         // Make sure the caller is a terminal of the project, and that the call is being made on behalf of an
         // interaction with the correct project.
         if (
-            !DIRECTORY.isTerminalOf({projectId: projectId, terminal: IJBTerminal(msg.sender)})
-                || context.projectId != projectId
+            !DIRECTORY.isTerminalOf({projectId: localProjectId, terminal: IJBTerminal(msg.sender)})
+                || context.projectId != localProjectId
         ) {
-            revert JB721Hook_InvalidPay({caller: msg.sender, contextProjectId: context.projectId, projectId: projectId});
+            revert JB721Hook_InvalidPay({
+                caller: msg.sender, contextProjectId: context.projectId, projectId: localProjectId
+            });
         }
 
         // Process the payment.
@@ -267,12 +269,12 @@ abstract contract JB721Hook is ERC721, IJB721Hook {
     function _didBurn(uint256[] memory tokenIds) internal virtual;
 
     /// @notice Initializes the contract by associating it with a project and adding ERC721 details.
-    /// @param projectId The ID of the project that this contract is associated with.
+    /// @param initialProjectId The ID of the project that this contract is associated with.
     /// @param name The name of the NFT collection.
     /// @param symbol The symbol representing the NFT collection.
-    function _initialize(uint256 projectId, string memory name, string memory symbol) internal {
-        ERC721._initialize({name_: name, symbol_: symbol});
-        PROJECT_ID = projectId;
+    function _initialize(uint256 initialProjectId, string memory name, string memory symbol) internal {
+        ERC721._initialize({collectionName: name, collectionSymbol: symbol});
+        projectId = initialProjectId;
     }
 
     /// @notice Process a received payment by minting NFTs and/or updating credits. Subclasses implement the

package/src/interfaces/IJB721Checkpoints.sol

@@ -11,7 +11,7 @@ interface IJB721Checkpoints is IERC5805 {
     /// @notice The hook that this module tracks voting power for.
     /// @return The hook address.
     // forge-lint: disable-next-line(mixed-case-function)
-    function HOOK() external view returns (address);
+    function hook() external view returns (address);
 
     /// @notice The owner of an NFT at a past block.
     /// @dev Returns `address(0)` for tokens that have never been enrolled (via `delegate(address, uint256[])`) or
@@ -36,8 +36,8 @@ interface IJB721Checkpoints is IERC5805 {
 
     /// @notice Initializes a cloned module with its hook reference.
     /// @dev Can only be called once. Called by the deployer after cloning.
-    /// @param hook The hook this module serves.
-    function initialize(address hook) external;
+    /// @param hookAddress The hook this module serves.
+    function initialize(address hookAddress) external;
 
     /// @notice Called by the hook after every NFT transfer to update checkpointed voting power.
     /// @dev Looks up the token's tier voting units from the store internally.

package/src/interfaces/IJB721Hook.sol

@@ -18,5 +18,5 @@ interface IJB721Hook is IJBRulesetDataHook, IJBPayHook, IJBCashOutHook {
 
     /// @notice The ID of the project that this contract is associated with.
     /// @return The project ID.
-    function PROJECT_ID() external view returns (uint256);
+    function projectId() external view returns (uint256);
 }

package/src/interfaces/IJB721TiersHook.sol

@@ -89,7 +89,7 @@ interface IJB721TiersHook is IJB721Hook {
     /// @param tierId The ID of the tier whose encoded IPFS URI was set.
     /// @param encodedUri The new encoded IPFS URI.
     /// @param caller The address that called the function.
-    event SetEncodedIPFSUri(uint256 indexed tierId, bytes32 encodedUri, address caller);
+    event SetEncodedIpfsUri(uint256 indexed tierId, bytes32 encodedUri, address caller);
 
     /// @notice Emitted when the token URI resolver is set.
     /// @param resolver The new token URI resolver.
@@ -140,8 +140,7 @@ interface IJB721TiersHook is IJB721Hook {
     /// @notice The checkpoint module that manages IVotes-compatible checkpointed voting power for this hook's NFTs.
     /// @dev Deployed lazily on first mint. Pass this to JBTokenDistributor as the IVotes token.
     /// @return The checkpoint module.
-    // forge-lint: disable-next-line(mixed-case-function)
-    function CHECKPOINTS() external view returns (IJB721Checkpoints);
+    function checkpoints() external view returns (IJB721Checkpoints);
 
     /// @notice The contract that exposes price feeds for currency conversions.
     /// @return The prices contract.
@@ -165,7 +164,7 @@ interface IJB721TiersHook is IJB721Hook {
     function adjustTiers(JB721TierConfig[] calldata tiersToAdd, uint256[] calldata tierIdsToRemove) external;
 
     /// @notice Initializes a cloned copy of the original `JB721TiersHook` contract.
-    /// @param projectId The ID of the project this hook is associated with.
+    /// @param initialProjectId The ID of the project this hook is associated with.
     /// @param name The name of the NFT collection.
     /// @param symbol The symbol representing the NFT collection.
     /// @param baseUri The URI to use as a base for full NFT `tokenUri`s.
@@ -174,7 +173,7 @@ interface IJB721TiersHook is IJB721Hook {
     /// @param tiersConfig The NFT tiers and pricing context to initialize the hook with.
     /// @param flags A set of additional options which dictate how the hook behaves.
     function initialize(
-        uint256 projectId,
+        uint256 initialProjectId,
         string memory name,
         string memory symbol,
         string memory baseUri,
@@ -217,16 +216,16 @@ interface IJB721TiersHook is IJB721Hook {
     /// @param tokenUriResolver The new URI resolver. Pass `IJB721TokenUriResolver(address(this))` as a sentinel value
     /// to leave unchanged. `address(this)` is used instead of `address(0)` because `address(0)` is a valid value that
     /// clears the resolver.
-    /// @param encodedIPFSUriTierId The ID of the tier to set the encoded IPFS URI of.
-    /// @param encodedIPFSUri The encoded IPFS URI to set.
+    /// @param encodedIpfsUriTierId The ID of the tier to set the encoded IPFS URI of.
+    /// @param encodedIpfsUri The encoded IPFS URI to set.
     function setMetadata(
         string calldata name,
         string calldata symbol,
         string calldata baseUri,
         string calldata contractUri,
         IJB721TokenUriResolver tokenUriResolver,
-        uint256 encodedIPFSUriTierId,
-        bytes32 encodedIPFSUri
+        uint256 encodedIpfsUriTierId,
+        bytes32 encodedIpfsUri
     )
         external;
 }

package/src/interfaces/IJB721TiersHookStore.sol

@@ -42,7 +42,7 @@ interface IJB721TiersHookStore {
     /// @param tierId The ID of the tier to get the encoded IPFS URI of.
     /// @return The encoded IPFS URI.
     // forge-lint: disable-next-line(mixed-case-function)
-    function encodedIPFSUriOf(address hook, uint256 tierId) external view returns (bytes32);
+    function encodedIpfsUriOf(address hook, uint256 tierId) external view returns (bytes32);
 
     /// @notice The encoded IPFS URI for the tier of the 721 with the provided token ID.
     /// @param hook The 721 contract that the encoded IPFS URI belongs to.
@@ -246,9 +246,9 @@ interface IJB721TiersHookStore {
 
     /// @notice Record a new encoded IPFS URI for a tier.
     /// @param tierId The ID of the tier to set the encoded IPFS URI of.
-    /// @param encodedIPFSUri The encoded IPFS URI to set for the tier.
+    /// @param encodedIpfsUri The encoded IPFS URI to set for the tier.
     // forge-lint: disable-next-line(mixed-case-function)
-    function recordSetEncodedIPFSUriOf(uint256 tierId, bytes32 encodedIPFSUri) external;
+    function recordSetEncodedIpfsUriOf(uint256 tierId, bytes32 encodedIpfsUri) external;
 
     /// @notice Record a newly set token URI resolver.
     /// @param resolver The resolver to set.

package/src/libraries/JB721TiersHookLib.sol

@@ -360,7 +360,7 @@ library JB721TiersHookLib {
         // attributable to tier splits. Downstream compositors (e.g. JBOmnichainDeployer) use this
         // to preserve split credit when an extra hook (buyback) returns weight=0.
         if (totalSplitAmount != 0 && context.amount.value != 0 && store.flagsOf(address(this)).issueTokensForSplits) {
-            splitCreditWeight = mulDiv(context.weight, totalSplitAmount, context.amount.value);
+            splitCreditWeight = mulDiv({x: context.weight, y: totalSplitAmount, denominator: context.amount.value});
         }
 
         // Resolve the effective beneficiary from payment metadata.
@@ -690,6 +690,149 @@ library JB721TiersHookLib {
     // ----------------------- private helpers --------------------------- //
     //*********************************************************************//
 
+    /// @notice Approves `terminal` to spend `amount` of `token`, calls `addToBalanceOf`, then revokes any
+    /// unconsumed allowance and reports the actual amount consumed via the allowance delta.
+    /// @dev Allowance-delta consumption protects against terminals that return successfully without pulling
+    /// the full granted amount, and the unconditional final `forceApprove(..., 0)` ensures no stale allowance
+    /// is left behind on either the success or failure path.
+    /// @param terminal The terminal to call.
+    /// @param token The ERC-20 token. Native must not be passed here.
+    /// @param projectId The destination project ID.
+    /// @param amount The amount to grant as allowance and request the terminal to pull.
+    /// @return consumed The amount actually consumed by the terminal (0 on revert; otherwise
+    /// `amount - remainingAllowance` after the call).
+    /// @return failureReason The revert reason from the terminal call, or empty bytes if the call succeeded.
+    function _approveAndAddToBalance(
+        IJBTerminal terminal,
+        address token,
+        uint256 projectId,
+        uint256 amount
+    )
+        private
+        returns (uint256 consumed, bytes memory failureReason)
+    {
+        // Grant the terminal allowance to pull up to `amount` of `token` from this contract. `forceApprove`
+        // sets the allowance to exactly `amount` regardless of any prior allowance, so a leftover non-zero
+        // allowance from a previous failed call cannot inflate this one.
+        SafeERC20.forceApprove({token: IERC20(token), spender: address(terminal), value: amount});
+
+        // Track whether the external call returned successfully. Initialized to `false` so a revert path
+        // leaves it unset and the consumption math below is skipped.
+        bool succeeded;
+
+        // Call the terminal's `addToBalanceOf` inside try/catch so a reverting terminal can't brick the
+        // surrounding payment. The terminal is expected to `transferFrom` against the allowance set above.
+        try terminal.addToBalanceOf({
+            projectId: projectId,
+            token: token,
+            amount: amount,
+            // Don't release any held fees on this call — fee returns are handled separately.
+            shouldReturnHeldFees: false,
+            // No memo or metadata is forwarded; the leftover routing is opaque to off-chain consumers.
+            memo: "",
+            metadata: bytes("")
+        }) {
+            // The terminal returned without reverting. The actual amount it consumed is measured below
+            // via the allowance delta — `succeeded` only records that there was no revert to report.
+            succeeded = true;
+        } catch (bytes memory reason) {
+            // The terminal reverted. Capture the reason so the caller can surface it via the
+            // `SplitPayoutReverted` event (or, for the leftover fallback, the
+            // `JB721TiersHookLib_SplitFallbackFailed` error) without re-throwing here.
+            failureReason = reason;
+        }
+
+        // On success, compute how much the terminal actually pulled. The post-call allowance equals
+        // `amount - actuallyConsumed` (since `forceApprove` set the pre-call allowance to `amount`), so
+        // `consumed = amount - postAllowance`. On failure, `succeeded` is `false` and `consumed` stays at
+        // its default `0`, which lets the caller route the full `amount` to the project's leftover balance.
+        if (succeeded) {
+            // Safe to use `unchecked`: `postAllowance` cannot exceed `amount` because the terminal can
+            // only decrement (via `transferFrom`) the allowance we just set to `amount`.
+            unchecked {
+                consumed = amount - IERC20(token).allowance({owner: address(this), spender: address(terminal)});
+            }
+        }
+
+        // Unconditionally revoke any remaining allowance. This is the load-bearing safety step — without
+        // it, a terminal that returns successfully without pulling the full `amount` would leave a stale
+        // non-zero allowance that the terminal could drain later. Running on both the success and failure
+        // paths means no allowance ever leaks out of this function.
+        SafeERC20.forceApprove({token: IERC20(token), spender: address(terminal), value: 0});
+    }
+
+    /// @notice Approves `terminal` to spend `amount` of `token`, calls `pay`, then revokes any unconsumed
+    /// allowance and reports the actual amount consumed via the allowance delta.
+    /// @dev Mirrors `_approveAndAddToBalance` for the `pay` entry point.
+    /// @param terminal The terminal to call.
+    /// @param token The ERC-20 token. Native must not be passed here.
+    /// @param projectId The destination project ID.
+    /// @param amount The amount to grant as allowance and request the terminal to pull.
+    /// @param beneficiary The beneficiary for the `pay` call.
+    /// @return consumed The amount actually consumed by the terminal.
+    /// @return failureReason The revert reason from the terminal call, or empty bytes on success.
+    function _approveAndPay(
+        IJBTerminal terminal,
+        address token,
+        uint256 projectId,
+        uint256 amount,
+        address payable beneficiary
+    )
+        private
+        returns (uint256 consumed, bytes memory failureReason)
+    {
+        // Grant the terminal allowance to pull up to `amount` of `token` from this contract. `forceApprove`
+        // sets the allowance to exactly `amount` regardless of any prior allowance, so a leftover non-zero
+        // allowance from a previous failed call cannot inflate this one.
+        SafeERC20.forceApprove({token: IERC20(token), spender: address(terminal), value: amount});
+
+        // Track whether the external call returned successfully. Initialized to `false` so a revert path
+        // leaves it unset and the consumption math below is skipped.
+        bool succeeded;
+
+        // Call the terminal's `pay` inside try/catch so a reverting terminal can't brick the surrounding
+        // payment. The terminal is expected to `transferFrom` against the allowance set above and mint
+        // project tokens to `beneficiary` in return.
+        try terminal.pay({
+            projectId: projectId,
+            token: token,
+            amount: amount,
+            beneficiary: beneficiary,
+            // No minimum is enforced on the terminal-side mint — the split-level minimum (if any) is
+            // enforced by the caller before reaching this helper.
+            minReturnedTokens: 0,
+            // No memo or metadata is forwarded; the leftover routing is opaque to off-chain consumers.
+            memo: "",
+            metadata: bytes("")
+        }) {
+            // The terminal returned without reverting. The actual amount it consumed is measured below
+            // via the allowance delta — `succeeded` only records that there was no revert to report.
+            succeeded = true;
+        } catch (bytes memory reason) {
+            // The terminal reverted. Capture the reason so the caller can surface it via the
+            // `SplitPayoutReverted` event without re-throwing here.
+            failureReason = reason;
+        }
+
+        // On success, compute how much the terminal actually pulled. The post-call allowance equals
+        // `amount - actuallyConsumed` (since `forceApprove` set the pre-call allowance to `amount`), so
+        // `consumed = amount - postAllowance`. On failure, `succeeded` is `false` and `consumed` stays at
+        // its default `0`, which lets the caller route the full `amount` to the project's leftover balance.
+        if (succeeded) {
+            // Safe to use `unchecked`: `postAllowance` cannot exceed `amount` because the terminal can
+            // only decrement (via `transferFrom`) the allowance we just set to `amount`.
+            unchecked {
+                consumed = amount - IERC20(token).allowance({owner: address(this), spender: address(terminal)});
+            }
+        }
+
+        // Unconditionally revoke any remaining allowance. This is the load-bearing safety step — without
+        // it, a terminal that returns successfully without pulling the full `amount` would leave a stale
+        // non-zero allowance that the terminal could drain later. Running on both the success and failure
+        // paths means no allowance ever leaks out of this function.
+        SafeERC20.forceApprove({token: IERC20(token), spender: address(terminal), value: 0});
+    }
+
     /// @notice Distributes funds for a single tier's split group.
     /// @dev `_sendPayoutToSplit` returns the actual amount that left this contract — `payoutAmount` on full
     /// success, `0` when the split fully fails (revert or missing recipient), or a partial value when an ERC-20
@@ -779,20 +922,16 @@ library JB721TiersHookLib {
                     });
                 }
             } else {
-                SafeERC20.forceApprove({token: IERC20(token), spender: address(terminal), value: leftoverAmount});
-                try terminal.addToBalanceOf({
-                    projectId: projectId,
-                    token: token,
-                    amount: leftoverAmount,
-                    shouldReturnHeldFees: false,
-                    memo: "",
-                    metadata: bytes("")
-                }) {}
-                catch (bytes memory reason) {
-                    // Reset approval on failure.
-                    SafeERC20.forceApprove({token: IERC20(token), spender: address(terminal), value: 0});
+                // Allowance-delta + unconditional cleanup: a terminal that returns successfully without pulling
+                // the full allowance would otherwise leave funds stranded in this library/hook and leak a
+                // non-zero allowance to the terminal. Fail closed: revert if either the call reverts OR the
+                // terminal under-consumed the granted allowance.
+                (uint256 consumed, bytes memory failureReason) = _approveAndAddToBalance({
+                    terminal: terminal, token: token, projectId: projectId, amount: leftoverAmount
+                });
+                if (failureReason.length != 0 || consumed != leftoverAmount) {
                     revert JB721TiersHookLib_SplitFallbackFailed({
-                        projectId: projectId, token: token, amount: leftoverAmount, reason: reason
+                        projectId: projectId, token: token, amount: leftoverAmount, reason: failureReason
                     });
                 }
             }
@@ -895,24 +1034,24 @@ library JB721TiersHookLib {
                         return 0;
                     }
                 } else {
-                    SafeERC20.forceApprove({token: IERC20(token), spender: address(terminal), value: amount});
-                    try terminal.addToBalanceOf({
-                        projectId: split.projectId,
-                        token: token,
-                        amount: amount,
-                        shouldReturnHeldFees: false,
-                        memo: "",
-                        metadata: bytes("")
-                    }) {
-                        return amount;
-                    } catch (bytes memory reason) {
-                        // Reset approval on failure so tokens aren't left approved to the terminal.
-                        SafeERC20.forceApprove({token: IERC20(token), spender: address(terminal), value: 0});
+                    // Allowance-delta + unconditional cleanup. `sent` reflects the amount the terminal actually
+                    // pulled; the unconsumed remainder (if any) stays in this contract and is routed back to the
+                    // project's leftover balance by the caller. On revert, `sent` stays 0 and the SplitPayoutReverted
+                    // event records the failure reason.
+                    bytes memory failureReason;
+                    (sent, failureReason) = _approveAndAddToBalance({
+                        terminal: terminal, token: token, projectId: split.projectId, amount: amount
+                    });
+                    if (failureReason.length != 0) {
                         emit SplitPayoutReverted({
-                            projectId: projectId, split: split, amount: amount, reason: reason, caller: msg.sender
+                            projectId: projectId,
+                            split: split,
+                            amount: amount,
+                            reason: failureReason,
+                            caller: msg.sender
                         });
-                        return 0;
                     }
+                    return sent;
                 }
             } else {
                 if (isNativeToken) {
@@ -933,25 +1072,25 @@ library JB721TiersHookLib {
                         return 0;
                     }
                 } else {
-                    SafeERC20.forceApprove({token: IERC20(token), spender: address(terminal), value: amount});
-                    try terminal.pay({
-                        projectId: split.projectId,
+                    // Same allowance-delta pattern as the `preferAddToBalance` branch, for the `pay` entry point.
+                    bytes memory failureReason;
+                    (sent, failureReason) = _approveAndPay({
+                        terminal: terminal,
                         token: token,
+                        projectId: split.projectId,
                         amount: amount,
-                        beneficiary: split.beneficiary,
-                        minReturnedTokens: 0,
-                        memo: "",
-                        metadata: bytes("")
-                    }) {
-                        return amount;
-                    } catch (bytes memory reason) {
-                        // Reset approval on failure so tokens aren't left approved to the terminal.
-                        SafeERC20.forceApprove({token: IERC20(token), spender: address(terminal), value: 0});
+                        beneficiary: split.beneficiary
+                    });
+                    if (failureReason.length != 0) {
                         emit SplitPayoutReverted({
-                            projectId: projectId, split: split, amount: amount, reason: reason, caller: msg.sender
+                            projectId: projectId,
+                            split: split,
+                            amount: amount,
+                            reason: failureReason,
+                            caller: msg.sender
                         });
-                        return 0;
                     }
+                    return sent;
                 }
             }
         } else if (split.beneficiary != address(0)) {

package/src/structs/JB721Tier.sol

@@ -12,7 +12,7 @@ import {JB721TierFlags} from "./JB721TierFlags.sol";
 /// tier. With a `reserveFrequency` of 5, an extra NFT will be minted for the `reserveBeneficiary` for every 5 NFTs
 /// purchased.
 /// @custom:member reserveBeneficiary The address which receives any reserve NFTs from this tier.
-/// @custom:member encodedIPFSUri The IPFS URI to use for each NFT in this tier.
+/// @custom:member encodedIpfsUri The IPFS URI to use for each NFT in this tier.
 /// @custom:member category The category that NFTs in this tier belongs to. Used to group NFT tiers.
 /// @custom:member discountPercent The discount that should be applied to the tier.
 /// @custom:member flags Boolean flags for this tier (allowOwnerMint, transfersPausable, cantBeRemoved,
@@ -29,7 +29,7 @@ struct JB721Tier {
     uint104 votingUnits;
     uint16 reserveFrequency;
     address reserveBeneficiary;
-    bytes32 encodedIPFSUri;
+    bytes32 encodedIpfsUri;
     uint24 category;
     uint8 discountPercent;
     JB721TierFlags flags;

package/src/structs/JB721TierConfig.sol

@@ -14,7 +14,7 @@ import {JB721TierConfigFlags} from "./JB721TierConfigFlags.sol";
 /// purchased.
 /// @custom:member reserveBeneficiary The address which receives any reserve NFTs from this tier. Overrides the default
 /// reserve beneficiary if one is set.
-/// @custom:member encodedIPFSUri The IPFS URI to use for each NFT in this tier.
+/// @custom:member encodedIpfsUri The IPFS URI to use for each NFT in this tier.
 /// @custom:member category The category that NFTs in this tier belongs to. Used to group NFT tiers.
 /// @custom:member discountPercent The discount that should be applied to the tier.
 /// @custom:member flags Boolean flags for this tier config (allowOwnerMint, useReserveBeneficiaryAsDefault,
@@ -29,7 +29,7 @@ struct JB721TierConfig {
     uint32 votingUnits;
     uint16 reserveFrequency;
     address reserveBeneficiary;
-    bytes32 encodedIPFSUri;
+    bytes32 encodedIpfsUri;
     uint24 category;
     uint8 discountPercent;
     JB721TierConfigFlags flags;

package/test/utils/ForTest_JB721TiersHook.sol

@@ -162,7 +162,7 @@ contract ForTest_JB721TiersHookStore is JB721TiersHookStore, IJB721TiersHookStor
                 votingUnits: storedTier.price,
                 reserveFrequency: storedTier.reserveFrequency,
                 reserveBeneficiary: reserveBeneficiaryOf(nft, currentSortIndex),
-                encodedIPFSUri: encodedIPFSUriOf[nft][currentSortIndex],
+                encodedIpfsUri: encodedIpfsUriOf[nft][currentSortIndex],
                 category: storedTier.category,
                 discountPercent: storedTier.discountPercent,
                 flags: JB721TierFlags({

package/test/utils/UnitTestSetup.sol

@@ -190,7 +190,7 @@ contract UnitTestSetup is Test {
             tiers[i].price = uint104((i + 1) * 10); // The price is `tierId` * 10.
             tiers[i].initialSupply = uint32(100);
             tiers[i].reserveBeneficiary = reserveBeneficiary;
-            tiers[i].encodedIPFSUri = tokenUris[i];
+            tiers[i].encodedIpfsUri = tokenUris[i];
             tiers[i].category = uint24(100);
             tiers[i].flags.useVotingUnits = true;
         }
@@ -325,7 +325,7 @@ contract UnitTestSetup is Test {
         assertEq(first.votingUnits, second.votingUnits);
         assertEq(first.reserveFrequency, second.reserveFrequency);
         assertEq(first.reserveBeneficiary, second.reserveBeneficiary);
-        assertEq(first.encodedIPFSUri, second.encodedIPFSUri);
+        assertEq(first.encodedIpfsUri, second.encodedIpfsUri);
     }
 
     // Compare two arrays of `JB721Tier`s.
@@ -339,7 +339,7 @@ contract UnitTestSetup is Test {
             assertEq(first[i].votingUnits, second[i].votingUnits);
             assertEq(first[i].reserveFrequency, second[i].reserveFrequency);
             assertEq(first[i].reserveBeneficiary, second[i].reserveBeneficiary);
-            assertEq(first[i].encodedIPFSUri, second[i].encodedIPFSUri);
+            assertEq(first[i].encodedIpfsUri, second[i].encodedIpfsUri);
         }
     }
 
@@ -390,7 +390,7 @@ contract UnitTestSetup is Test {
                 && first.initialSupply == second.initialSupply && first.votingUnits == second.votingUnits
                 && first.reserveFrequency == second.reserveFrequency
                 && first.reserveBeneficiary == second.reserveBeneficiary
-                && first.encodedIPFSUri == second.encodedIPFSUri
+                && first.encodedIpfsUri == second.encodedIpfsUri
                 && keccak256(abi.encodePacked(first.resolvedUri)) == keccak256(abi.encodePacked(second.resolvedUri)));
     }
 
@@ -516,7 +516,7 @@ contract UnitTestSetup is Test {
                 votingUnits: tierConfig.votingUnits,
                 reserveFrequency: tierConfig.reserveFrequency,
                 reserveBeneficiary: reserveBeneficiary,
-                encodedIPFSUri: i < tokenUris.length ? tokenUris[i] : tokenUris[0],
+                encodedIpfsUri: i < tokenUris.length ? tokenUris[i] : tokenUris[0],
                 category: categoryIncrement == 0
                     // forge-lint: disable-next-line(unsafe-typecast)
                     ? tierConfig.category == type(uint24).max ? uint24(i * 2 + 1) : tierConfig.category
@@ -545,7 +545,7 @@ contract UnitTestSetup is Test {
                 votingUnits: tierConfigs[i].votingUnits,
                 reserveFrequency: tierConfigs[i].reserveFrequency,
                 reserveBeneficiary: tierConfigs[i].reserveBeneficiary,
-                encodedIPFSUri: tierConfigs[i].encodedIPFSUri,
+                encodedIpfsUri: tierConfigs[i].encodedIpfsUri,
                 category: tierConfigs[i].category,
                 discountPercent: tierConfigs[i].discountPercent,
                 flags: JB721TierFlags({
@@ -556,7 +556,7 @@ contract UnitTestSetup is Test {
                     cantBuyWithCredits: tierConfigs[i].flags.cantBuyWithCredits
                 }),
                 splitPercent: tierConfigs[i].splitPercent,
-                resolvedUri: defaultTierConfig.encodedIPFSUri == bytes32(0)
+                resolvedUri: defaultTierConfig.encodedIpfsUri == bytes32(0)
                     ? ""
                     : string(abi.encodePacked("resolverURI", _generateTokenId(initialId + i + 1, 0)))
             });
@@ -721,7 +721,7 @@ contract UnitTestSetup is Test {
                 votingUnits: uint16(0),
                 reserveFrequency: uint16(0),
                 reserveBeneficiary: reserveBeneficiary,
-                encodedIPFSUri: tokenUris[i],
+                encodedIpfsUri: tokenUris[i],
                 category: uint24(100),
                 discountPercent: uint8(0),
                 flags: JB721TierConfigFlags({