@bananapus/721-hook-v6 0.0.32 → 0.0.34

package/USER_JOURNEYS.md

@@ -81,6 +81,17 @@
 2. Keep collection-specific behavior in the downstream repo while leaving pay, reserve, and cash-out semantics in this repo.
 3. Audit hook-store interactions here first, then audit the downstream resolver or wrapper.
 
+## Journey 7: Mint NFTs To The Correct Beneficiary During Cross-Chain Payments
+
+**Starting state:** a sucker pays the project on behalf of a remote user via `payRemote`, and the 721 hook needs to mint NFTs and accrue credits to the real user instead of the sucker contract.
+
+**Success:** NFTs mint to and pay credits accrue to the real remote user.
+
+**Flow**
+1. The sucker calls `terminal.pay()` with itself as both payer and beneficiary, embedding the real user's address in the `JB_RELAY_BENEFICIARY` metadata key.
+2. `_mintAndUpdateCredits` detects that `payer == beneficiary` and finds relay-beneficiary metadata.
+3. All NFT minting and credit accounting uses the resolved relay beneficiary instead of the sucker address.
+
 ## Hand-Offs
 
 - Use [nana-core-v6](../nana-core-v6/USER_JOURNEYS.md) for the treasury, ruleset, and permission surfaces the hook plugs into.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/721-hook-v6",
-  "version": "0.0.32",
+  "version": "0.0.34",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -18,9 +18,9 @@
   },
   "dependencies": {
     "@bananapus/address-registry-v6": "^0.0.17",
-    "@bananapus/core-v6": "^0.0.32",
+    "@bananapus/core-v6": "^0.0.34",
     "@bananapus/ownable-v6": "^0.0.17",
-    "@bananapus/permission-ids-v6": "^0.0.15",
+    "@bananapus/permission-ids-v6": "^0.0.17",
     "@openzeppelin/contracts": "^5.6.1",
     "@prb/math": "^4.1.0",
     "solady": "^0.1.8"

package/script/Deploy.s.sol

@@ -10,6 +10,8 @@ import {
 import {Sphinx} from "@sphinx-labs/contracts/contracts/foundry/SphinxPlugin.sol";
 import {Script} from "forge-std/Script.sol";
 
+import {JB721CheckpointsDeployer} from "../src/JB721CheckpointsDeployer.sol";
+import {IJB721CheckpointsDeployer} from "../src/interfaces/IJB721CheckpointsDeployer.sol";
 import {JB721TiersHookDeployer} from "../src/JB721TiersHookDeployer.sol";
 import {JB721TiersHookProjectDeployer} from "../src/JB721TiersHookProjectDeployer.sol";
 import {JB721TiersHookStore} from "../src/JB721TiersHookStore.sol";
@@ -34,6 +36,8 @@ contract DeployScript is Script, Sphinx {
     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";
 
     function configureSphinx() public override {
         sphinxConfig.projectName = "nana-721-hook-v6";
@@ -69,28 +73,58 @@ contract DeployScript is Script, Sphinx {
         JB721TiersHookStore store;
         {
             // Perform the check for the store.
-            (address _store, bool _storeIsDeployed) =
-                _isDeployed(HOOK_STORE_SALT, type(JB721TiersHookStore).creationCode, "");
+            (address _store, bool _storeIsDeployed) = _isDeployed({
+                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);
         }
 
+        JB721CheckpointsDeployer checkpointsDeployer;
+        {
+            // Perform the check for the deployer.
+            (address _deployer, bool _deployerIsDeployed) = _isDeployed({
+                salt: CHECKPOINTS_DEPLOYER_SALT,
+                creationCode: type(JB721CheckpointsDeployer).creationCode,
+                arguments: ""
+            });
+
+            // Deploy it if it has not been deployed yet.
+            checkpointsDeployer = !_deployerIsDeployed
+                ? new JB721CheckpointsDeployer{salt: CHECKPOINTS_DEPLOYER_SALT}()
+                : JB721CheckpointsDeployer(_deployer);
+        }
+
         JB721TiersHook hook;
         {
             // Perform the check for the registry.
-            (address _hook, bool _hookIsDeployed) = _isDeployed(
-                HOOK_SALT,
-                type(JB721TiersHook).creationCode,
-                abi.encode(
-                    core.directory, core.permissions, core.prices, core.rulesets, store, core.splits, TRUSTED_FORWARDER
+            (address _hook, bool _hookIsDeployed) = _isDeployed({
+                salt: HOOK_SALT,
+                creationCode: type(JB721TiersHook).creationCode,
+                arguments: abi.encode(
+                    core.directory,
+                    core.permissions,
+                    core.prices,
+                    core.rulesets,
+                    store,
+                    core.splits,
+                    checkpointsDeployer,
+                    TRUSTED_FORWARDER
                 )
-            );
+            });
 
             // 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, TRUSTED_FORWARDER
+                    core.directory,
+                    core.permissions,
+                    core.prices,
+                    core.rulesets,
+                    store,
+                    core.splits,
+                    IJB721CheckpointsDeployer(address(checkpointsDeployer)),
+                    TRUSTED_FORWARDER
                 )
                 : JB721TiersHook(_hook);
         }
@@ -98,11 +132,11 @@ contract DeployScript is Script, Sphinx {
         JB721TiersHookDeployer hookDeployer;
         {
             // Perform the check for the registry.
-            (address _hookDeployer, bool _hookDeployerIsDeployed) = _isDeployed(
-                HOOK_DEPLOYER_SALT,
-                type(JB721TiersHookDeployer).creationCode,
-                abi.encode(hook, store, registry.registry, TRUSTED_FORWARDER)
-            );
+            (address _hookDeployer, bool _hookDeployerIsDeployed) = _isDeployed({
+                salt: HOOK_DEPLOYER_SALT,
+                creationCode: type(JB721TiersHookDeployer).creationCode,
+                arguments: abi.encode(hook, store, registry.registry, TRUSTED_FORWARDER)
+            });
 
             hookDeployer = !_hookDeployerIsDeployed
                 ? new JB721TiersHookDeployer{salt: HOOK_DEPLOYER_SALT}(
@@ -114,11 +148,11 @@ contract DeployScript is Script, Sphinx {
         JB721TiersHookProjectDeployer projectDeployer;
         {
             // Perform the check for the registry.
-            (address _projectDeployer, bool _projectDeployerIsdeployed) = _isDeployed(
-                PROJECT_DEPLOYER_SALT,
-                type(JB721TiersHookProjectDeployer).creationCode,
-                abi.encode(core.directory, core.permissions, hookDeployer, TRUSTED_FORWARDER)
-            );
+            (address _projectDeployer, bool _projectDeployerIsdeployed) = _isDeployed({
+                salt: PROJECT_DEPLOYER_SALT,
+                creationCode: type(JB721TiersHookProjectDeployer).creationCode,
+                arguments: abi.encode(core.directory, core.permissions, hookDeployer, TRUSTED_FORWARDER)
+            });
 
             projectDeployer = !_projectDeployerIsdeployed
                 ? new JB721TiersHookProjectDeployer{salt: PROJECT_DEPLOYER_SALT}(

package/src/JB721Checkpoints.sol

@@ -0,0 +1,92 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.28;
+
+import {EIP712} from "@openzeppelin/contracts/utils/cryptography/EIP712.sol";
+import {Votes} from "@openzeppelin/contracts/governance/utils/Votes.sol";
+import {IJB721Checkpoints} from "./interfaces/IJB721Checkpoints.sol";
+import {IJB721TiersHookStore} from "./interfaces/IJB721TiersHookStore.sol";
+
+/// @title JB721Checkpoints
+/// @notice Provides IVotes-compatible checkpointed voting power for a JB721TiersHook. Deployed as an EIP-1167 clone
+/// via JB721CheckpointsDeployer — one module per hook. The hook calls `onTransfer` on every NFT transfer to
+/// maintain accurate vote checkpoints.
+/// @dev EIP712 on clones: OZ stores name/version as immutables (accessible via DELEGATECALL). The storage cache
+/// (`_cachedThis`) is uninitialized on clones, so `domainSeparatorV4()` always rebuilds using the clone's
+/// `address(this)` — correct behavior, tiny gas overhead.
+contract JB721Checkpoints is Votes, IJB721Checkpoints {
+    //*********************************************************************//
+    // --------------------------- custom errors ------------------------- //
+    //*********************************************************************//
+
+    error JB721Checkpoints_AlreadyInitialized();
+    error JB721Checkpoints_Unauthorized();
+
+    //*********************************************************************//
+    // --------------------- private stored properties ------------------ //
+    //*********************************************************************//
+
+    /// @notice Whether this contract has been initialized.
+    bool private _initialized;
+
+    //*********************************************************************//
+    // ---------------------- public stored properties ------------------- //
+    //*********************************************************************//
+
+    /// @notice The hook that this module tracks voting power for.
+    address public override HOOK;
+
+    /// @notice The store that holds tier and voting data for the hook's NFTs.
+    IJB721TiersHookStore public override STORE;
+
+    //*********************************************************************//
+    // -------------------------- constructor ---------------------------- //
+    //*********************************************************************//
+
+    /// @dev Parameterless. The implementation contract is initialized in the constructor to prevent direct use.
+    /// Clones are initialized via `initialize()`.
+    constructor() EIP712("JB721Checkpoints", "1") {
+        _initialized = true;
+    }
+
+    //*********************************************************************//
+    // ---------------------- external transactions ---------------------- //
+    //*********************************************************************//
+
+    /// @notice Initializes a cloned module with its hook and store references.
+    /// @dev Can only be called once. Called by the deployer after cloning.
+    /// @param hook The hook this module serves.
+    /// @param store The store that holds tier data for the hook's NFTs.
+    function initialize(address hook, IJB721TiersHookStore store) external override {
+        if (_initialized) revert JB721Checkpoints_AlreadyInitialized();
+        _initialized = true;
+        HOOK = hook;
+        STORE = store;
+    }
+
+    /// @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.
+    /// @param from The previous owner (address(0) on mint).
+    /// @param to The new owner (address(0) on burn).
+    /// @param tokenId The token ID being transferred.
+    function onTransfer(address from, address to, uint256 tokenId) external override {
+        if (msg.sender != HOOK) revert JB721Checkpoints_Unauthorized();
+
+        // Look up this token's tier to get its voting units.
+        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});
+    }
+
+    //*********************************************************************//
+    // ------------------------ internal functions ----------------------- //
+    //*********************************************************************//
+
+    /// @notice Returns the total voting units held by an account (across all tiers).
+    /// @dev Called by OZ Votes when re-delegating to compute the account's total voting units.
+    /// @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});
+    }
+}

package/src/JB721CheckpointsDeployer.sol

@@ -0,0 +1,45 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.28;
+
+import {LibClone} from "solady/src/utils/LibClone.sol";
+import {JB721Checkpoints} from "./JB721Checkpoints.sol";
+import {IJB721Checkpoints} from "./interfaces/IJB721Checkpoints.sol";
+import {IJB721CheckpointsDeployer} from "./interfaces/IJB721CheckpointsDeployer.sol";
+import {IJB721TiersHookStore} from "./interfaces/IJB721TiersHookStore.sol";
+
+/// @title JB721CheckpointsDeployer
+/// @notice Deploys EIP-1167 clones of JB721Checkpoints for each JB721TiersHook instance.
+/// @dev The implementation is deployed once in the constructor. Each `deploy()` call clones it (~45k gas) and
+/// initializes the clone with the hook and store references.
+contract JB721CheckpointsDeployer is IJB721CheckpointsDeployer {
+    //*********************************************************************//
+    // --------------- public immutable stored properties ---------------- //
+    //*********************************************************************//
+
+    /// @notice The checkpoint module implementation that clones delegate to.
+    address public immutable override IMPLEMENTATION;
+
+    //*********************************************************************//
+    // -------------------------- constructor ---------------------------- //
+    //*********************************************************************//
+
+    constructor() {
+        IMPLEMENTATION = address(new JB721Checkpoints());
+    }
+
+    //*********************************************************************//
+    // ---------------------- external transactions ---------------------- //
+    //*********************************************************************//
+
+    /// @notice Deploys a new deterministic checkpoint clone for the given hook.
+    /// @dev Uses CREATE2 with the hook address as salt so the clone address is the same across chains.
+    /// @param hook The hook address the module will serve.
+    /// @param store The store that holds tier data for the hook's NFTs.
+    /// @return module The newly deployed and initialized checkpoint module.
+    function deploy(address hook, IJB721TiersHookStore store) external override returns (IJB721Checkpoints module) {
+        module = IJB721Checkpoints(
+            LibClone.cloneDeterministic({implementation: IMPLEMENTATION, salt: bytes32(uint256(uint160(hook)))})
+        );
+        module.initialize({hook: hook, store: store});
+    }
+}

package/src/JB721TiersHook.sol

@@ -19,9 +19,12 @@ import {ERC2771Context} from "@openzeppelin/contracts/metatx/ERC2771Context.sol"
 import {Context} from "@openzeppelin/contracts/utils/Context.sol";
 import {IERC165} from "@openzeppelin/contracts/utils/introspection/IERC165.sol";
 import {JB721Hook} from "./abstract/JB721Hook.sol";
+import {IJB721Checkpoints} from "./interfaces/IJB721Checkpoints.sol";
+import {IJB721CheckpointsDeployer} from "./interfaces/IJB721CheckpointsDeployer.sol";
 import {IJB721TiersHook} from "./interfaces/IJB721TiersHook.sol";
 import {IJB721TiersHookStore} from "./interfaces/IJB721TiersHookStore.sol";
 import {IJB721TokenUriResolver} from "./interfaces/IJB721TokenUriResolver.sol";
+import {JB721Constants} from "./libraries/JB721Constants.sol";
 import {JB721TiersHookLib} from "./libraries/JB721TiersHookLib.sol";
 import {JB721TiersRulesetMetadataResolver} from "./libraries/JB721TiersRulesetMetadataResolver.sol";
 import {JB721InitTiersConfig} from "./structs/JB721InitTiersConfig.sol";
@@ -42,7 +45,6 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
 
     error JB721TiersHook_AlreadyInitialized(uint256 projectId);
     error JB721TiersHook_CantBuyWithCredits();
-    error JB721TiersHook_CurrencyMismatch(uint256 paymentCurrency, uint256 tierCurrency);
     error JB721TiersHook_InvalidPricingDecimals(uint256 decimals);
     error JB721TiersHook_MintReserveNftsPaused();
     error JB721TiersHook_NoProjectId();
@@ -65,6 +67,9 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
     /// @notice The contract that stores and manages splits.
     IJBSplits public immutable override SPLITS;
 
+    /// @notice The deployer used to deploy checkpoint module clones during initialization.
+    IJB721CheckpointsDeployer internal immutable CHECKPOINTS_DEPLOYER;
+
     //*********************************************************************//
     // --------------------- private stored properties ------------------ //
     //*********************************************************************//
@@ -104,6 +109,10 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
     /// - pricing decimals in bits 32-39 (8 bits).
     uint256 internal _packedPricingContext;
 
+    /// @notice The checkpoint module that manages IVotes-compatible checkpointed voting power for this hook's NFTs.
+    /// @dev Set once during `initialize()`. Pass this to JBTokenDistributor as the IVotes token.
+    IJB721Checkpoints public override CHECKPOINTS;
+
     //*********************************************************************//
     // -------------------------- constructor ---------------------------- //
     //*********************************************************************//
@@ -114,6 +123,7 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
     /// @param rulesets A contract storing and managing project rulesets.
     /// @param store The contract which stores the NFT's data.
     /// @param splits The contract that stores and manages splits.
+    /// @param checkpointsDeployer The deployer used to deploy checkpoint module clones during initialization.
     /// @param trustedForwarder The trusted forwarder for the ERC2771Context.
     constructor(
         IJBDirectory directory,
@@ -122,6 +132,7 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
         IJBRulesets rulesets,
         IJB721TiersHookStore store,
         IJBSplits splits,
+        IJB721CheckpointsDeployer checkpointsDeployer,
         address trustedForwarder
     )
         JBOwnable(permissions, directory.PROJECTS(), msg.sender, uint88(0))
@@ -132,6 +143,7 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
         RULESETS = rulesets;
         STORE = store;
         SPLITS = splits;
+        CHECKPOINTS_DEPLOYER = checkpointsDeployer;
 
         // Prevent the implementation contract from being initialized.
         _initialized = true;
@@ -146,14 +158,8 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
     /// @param tokenId The token ID of the NFT to get the first owner of.
     /// @return The address of the NFT's first owner.
     function firstOwnerOf(uint256 tokenId) external view override returns (address) {
-        // Get a reference to the first owner.
-        address storedFirstOwner = _firstOwnerOf[tokenId];
-
-        // If the stored first owner is set, return it.
-        if (storedFirstOwner != address(0)) return storedFirstOwner;
-
-        // Otherwise, the first owner must be the current owner.
-        return _ownerOf(tokenId);
+        address first = _firstOwnerOf[tokenId];
+        return first != address(0) ? first : _ownerOf(tokenId);
     }
 
     /// @notice Context for the pricing of this hook's tiers.
@@ -196,37 +202,24 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
     {
         hookSpecifications = new JBPayHookSpecification[](1);
 
-        // Calculate per-tier split amounts via the library.
-        (uint256 totalSplitAmount, bytes memory splitMetadata) = JB721TiersHookLib.calculateSplitAmounts({
-            store: STORE, hook: address(this), metadataIdTarget: METADATA_ID_TARGET, metadata: context.metadata
-        });
-
-        // Convert split amounts from tier pricing to payment token denomination (if currencies differ)
-        // and cap at the actual payment value so the terminal never forwards more than was paid.
-        if (totalSplitAmount != 0) {
-            (totalSplitAmount, splitMetadata) = JB721TiersHookLib.convertAndCapSplitAmounts({
-                totalSplitAmount: totalSplitAmount,
-                splitMetadata: splitMetadata,
-                packedPricingContext: _packedPricingContext,
-                prices: PRICES,
-                projectId: context.projectId,
-                amountCurrency: context.amount.currency,
-                amountDecimals: context.amount.decimals,
-                amountValue: context.amount.value
-            });
-        }
-
-        // Adjust weight so the terminal mints tokens only for the amount that actually enters the project.
-        weight = JB721TiersHookLib.calculateWeight({
-            contextWeight: context.weight,
-            amountValue: context.amount.value,
-            totalSplitAmount: totalSplitAmount,
+        // Compute split amounts, adjusted weight, and resolved beneficiary in a single library call.
+        uint256 totalSplitAmount;
+        bytes memory splitMetadata;
+        address beneficiary;
+        (weight, totalSplitAmount, splitMetadata, beneficiary) = JB721TiersHookLib.computeSplitsAndWeight({
             store: STORE,
-            hook: address(this)
+            metadataIdTarget: METADATA_ID_TARGET,
+            packedPricingContext: _packedPricingContext,
+            prices: PRICES,
+            context: context
         });
 
-        hookSpecifications[0] =
-            JBPayHookSpecification({hook: this, noop: false, amount: totalSplitAmount, metadata: splitMetadata});
+        hookSpecifications[0] = JBPayHookSpecification({
+            hook: this,
+            noop: false,
+            amount: totalSplitAmount,
+            metadata: abi.encode(beneficiary, context.payer, splitMetadata)
+        });
     }
 
     /// @notice The combined cash out weight of the NFTs with the specified token IDs.
@@ -314,6 +307,9 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
                 || flags.preventOverspending || flags.issueTokensForSplits
         ) STORE.recordFlags(flags);
 
+        // Deploy the checkpoint module for IVotes-compatible voting power.
+        CHECKPOINTS = CHECKPOINTS_DEPLOYER.deploy({hook: address(this), store: STORE});
+
         // Transfer ownership to the initializer.
         _transferOwnership(_msgSender());
     }
@@ -321,7 +317,7 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
     /// @notice Indicates if this contract adheres to the specified interface.
     /// @dev See {IERC165-supportsInterface}.
     /// @param interfaceId The ID of the interface to check for adherence to.
-    function supportsInterface(bytes4 interfaceId) public view override(IERC165, JB721Hook) returns (bool) {
+    function supportsInterface(bytes4 interfaceId) public view virtual override(IERC165, JB721Hook) returns (bool) {
         return interfaceId == type(IJB721TiersHook).interfaceId || JB721Hook.supportsInterface(interfaceId);
     }
 
@@ -579,13 +575,13 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
 
     /// @notice Returns the calldata, preferred to use over `msg.data`
     /// @return calldata the `msg.data` of this call
-    function _msgData() internal view override(ERC2771Context, Context) returns (bytes calldata) {
+    function _msgData() internal view virtual override(ERC2771Context, Context) returns (bytes calldata) {
         return ERC2771Context._msgData();
     }
 
     /// @notice Returns the sender, preferred to use over `msg.sender`
     /// @return sender the sender address of this call.
-    function _msgSender() internal view override(ERC2771Context, Context) returns (address sender) {
+    function _msgSender() internal view virtual override(ERC2771Context, Context) returns (address sender) {
         return ERC2771Context._msgSender();
     }
 
@@ -636,97 +632,60 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
 
     /// @notice Mint NFTs from the specified tiers and update the beneficiary's pay credits.
     /// @param value The normalized payment value.
-    /// @param context Payment context provided by the terminal.
-    function _mintAndUpdateCredits(uint256 value, JBAfterPayRecordedContext calldata context) internal {
+    /// @param payer The address that initiated the payment.
+    /// @param payerMetadata The metadata provided by the payer.
+    /// @param beneficiary The address to mint NFTs to and track credits for.
+    function _mintAndUpdateCredits(
+        uint256 value,
+        address payer,
+        bytes calldata payerMetadata,
+        address beneficiary
+    )
+        internal
+    {
         // Keep a reference to the number of NFT credits the beneficiary already has.
-        uint256 payCredits = payCreditsOf[context.beneficiary];
-
-        // Set the leftover amount as the initial value.
-        uint256 leftoverAmount = value;
-
-        // If the payer is the beneficiary, combine their NFT credits with the amount paid.
-        uint256 unusedPayCredits;
-        if (context.payer == context.beneficiary) {
-            leftoverAmount += payCredits;
-        } else {
-            // Otherwise, the payer's NFT credits won't be used, and we keep track of the unused credits.
-            unusedPayCredits = payCredits;
-        }
+        uint256 payCredits = payCreditsOf[beneficiary];
 
-        // Keep a reference to the boolean indicating whether paying more than the price of the NFTs being minted
-        // is allowed. Defaults to the collection's flag.
-        bool allowOverspending = !STORE.flagsOf(address(this)).preventOverspending;
-
-        // Resolve the metadata.
-        (bool found, bytes memory metadata) = JBMetadataResolver.getDataFor({
-            id: JBMetadataResolver.getId({purpose: "pay", target: METADATA_ID_TARGET}), metadata: context.payerMetadata
+        // Compute the mint: combine credits, decode metadata, record mint, and check overspending.
+        (uint256[] memory tokenIds, uint16[] memory tierIdsToMint, uint256 newPayCredits) = JB721TiersHookLib.prepareMint({
+            store: STORE,
+            metadataIdTarget: METADATA_ID_TARGET,
+            value: value,
+            payer: payer,
+            beneficiary: beneficiary,
+            payCredits: payCredits,
+            payerMetadata: payerMetadata
         });
 
-        if (found) {
-            // Keep a reference to the IDs of the tier be to minted.
-            uint16[] memory tierIdsToMint;
-
-            // Keep a reference to the payer's flag indicating whether overspending is allowed.
-            bool payerAllowsOverspending;
-
-            // Decode the metadata.
-            (payerAllowsOverspending, tierIdsToMint) = abi.decode(metadata, (bool, uint16[]));
-
-            // Make sure overspending is allowed if requested.
-            if (allowOverspending && !payerAllowsOverspending) {
-                allowOverspending = false;
-            }
-
-            // Mint NFTs from the tiers as specified.
-            if (tierIdsToMint.length != 0) {
-                uint256[] memory tokenIds;
-                uint256 restrictedCost;
-                uint256 totalAmountPaid = leftoverAmount;
-
-                // Record the mints.
-                // slither-disable-next-line reentrancy-events,reentrancy-no-eth
-                (tokenIds, leftoverAmount, restrictedCost) =
-                    STORE.recordMint({amount: leftoverAmount, tierIds: tierIdsToMint, isOwnerMint: false});
-
-                // Enforce `cantBuyWithCredits`: only tiers explicitly configured as credit-restricted must be fully
-                // covered by fresh payment (not stored credits). Split-bearing tiers are not automatically restricted;
-                // deployers must set that flag in tier configuration when they need that invariant.
-                if (restrictedCost > value) revert JB721TiersHook_CantBuyWithCredits();
-
-                // Mint each token.
-                _mintTokens({
-                    tokenIds: tokenIds,
-                    tierIds: tierIdsToMint,
-                    beneficiary: context.beneficiary,
-                    totalAmountPaid: totalAmountPaid
-                });
-            }
+        // Mint each token to the effective beneficiary.
+        if (tokenIds.length != 0) {
+            // totalAmountPaid is the full amount available before recordMint deducted tier prices.
+            uint256 totalAmountPaid = (payer == beneficiary) ? value + payCredits : value;
+            _mintTokens({
+                tokenIds: tokenIds, tierIds: tierIdsToMint, beneficiary: beneficiary, totalAmountPaid: totalAmountPaid
+            });
         }
 
-        // If overspending isn't allowed, revert.
-        if (leftoverAmount != 0 && !allowOverspending) revert JB721TiersHook_Overspending(leftoverAmount);
-
         // Update NFT credits if they changed.
-        uint256 newPayCredits = leftoverAmount + unusedPayCredits;
-
         if (newPayCredits != payCredits) {
             if (newPayCredits > payCredits) {
                 emit AddPayCredits({
                     amount: newPayCredits - payCredits,
                     newTotalCredits: newPayCredits,
-                    account: context.beneficiary,
+                    account: beneficiary,
                     caller: _msgSender()
                 });
             } else {
                 emit UsePayCredits({
                     amount: payCredits - newPayCredits,
                     newTotalCredits: newPayCredits,
-                    account: context.beneficiary,
+                    account: beneficiary,
                     caller: _msgSender()
                 });
             }
 
-            payCreditsOf[context.beneficiary] = newPayCredits;
+            // slither-disable-next-line reentrancy-no-eth
+            payCreditsOf[beneficiary] = newPayCredits;
         }
     }
 
@@ -749,11 +708,24 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
         });
         if (!valid) return;
 
+        // Decode the beneficiary and payer forwarded from beforePayRecordedWith.
+        address beneficiary;
+        address payer;
+        bytes memory splitData;
+        if (context.hookMetadata.length != 0) {
+            (beneficiary, payer, splitData) = abi.decode(context.hookMetadata, (address, address, bytes));
+        }
+        // Fall back to context values if none were forwarded.
+        if (beneficiary == address(0)) beneficiary = context.beneficiary;
+        if (payer == address(0)) payer = context.payer;
+
         // Mint NFTs from the specified tiers and update the beneficiary's pay credits.
-        _mintAndUpdateCredits({value: value, context: context});
+        _mintAndUpdateCredits({
+            value: value, payer: payer, payerMetadata: context.payerMetadata, beneficiary: beneficiary
+        });
 
         // Distribute any forwarded funds to tier split groups.
-        if (context.hookMetadata.length != 0 && context.forwardedAmount.value != 0) {
+        if (splitData.length != 0 && context.forwardedAmount.value != 0) {
             JB721TiersHookLib.distributeAll({
                 directory: DIRECTORY,
                 splits: SPLITS,
@@ -762,7 +734,7 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
                 token: context.forwardedAmount.token,
                 amount: context.forwardedAmount.value,
                 decimals: context.forwardedAmount.decimals,
-                encodedSplitData: context.hookMetadata
+                encodedSplitData: splitData
             });
         }
     }
@@ -779,11 +751,10 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
     /// @param tierId The ID of the tier to set the discount percent for.
     /// @param discountPercent The discount percent to set for the tier.
     function _setDiscountPercentOf(uint256 tierId, uint256 discountPercent) internal {
-        emit SetDiscountPercent({tierId: tierId, discountPercent: discountPercent, caller: _msgSender()});
-
-        // Record the discount percent for the tier.
         // slither-disable-next-line calls-loop
-        STORE.recordSetDiscountPercentOf({tierId: tierId, discountPercent: discountPercent});
+        JB721TiersHookLib.setDiscountPercentOf({
+            store: STORE, tierId: tierId, discountPercent: discountPercent, caller: _msgSender()
+        });
     }
 
     /// @notice Before transferring an NFT, register its first owner (if necessary).
@@ -822,5 +793,8 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
         // Record the transfer.
         // slither-disable-next-line reentrency-events,calls-loop
         STORE.recordTransferForTier({tierId: tierId, from: from, to: to});
+
+        // Notify the checkpoint module to update checkpointed voting power.
+        CHECKPOINTS.onTransfer({from: from, to: to, tokenId: tokenId});
     }
 }