@bananapus/721-hook-v6 0.0.32 → 0.0.33

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.33",
   "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,6 +19,8 @@ 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";
@@ -42,7 +44,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 +66,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 +108,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 +122,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 +131,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 +142,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 +157,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.
@@ -225,8 +230,12 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
             hook: address(this)
         });
 
-        hookSpecifications[0] =
-            JBPayHookSpecification({hook: this, noop: false, amount: totalSplitAmount, metadata: splitMetadata});
+        hookSpecifications[0] = JBPayHookSpecification({
+            hook: this,
+            noop: false,
+            amount: totalSplitAmount,
+            metadata: abi.encode(context.beneficiary, context.payer, splitMetadata)
+        });
     }
 
     /// @notice The combined cash out weight of the NFTs with the specified token IDs.
@@ -314,6 +323,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 +333,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 +591,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,17 +648,26 @@ 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];
+        uint256 payCredits = payCreditsOf[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.
+        // If the payer is the effective beneficiary, combine their NFT credits with the amount paid.
         uint256 unusedPayCredits;
-        if (context.payer == context.beneficiary) {
+        if (payer == beneficiary) {
             leftoverAmount += payCredits;
         } else {
             // Otherwise, the payer's NFT credits won't be used, and we keep track of the unused credits.
@@ -659,7 +680,7 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
 
         // Resolve the metadata.
         (bool found, bytes memory metadata) = JBMetadataResolver.getDataFor({
-            id: JBMetadataResolver.getId({purpose: "pay", target: METADATA_ID_TARGET}), metadata: context.payerMetadata
+            id: JBMetadataResolver.getId({purpose: "pay", target: METADATA_ID_TARGET}), metadata: payerMetadata
         });
 
         if (found) {
@@ -693,11 +714,11 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
                 // deployers must set that flag in tier configuration when they need that invariant.
                 if (restrictedCost > value) revert JB721TiersHook_CantBuyWithCredits();
 
-                // Mint each token.
+                // Mint each token to the effective beneficiary.
                 _mintTokens({
                     tokenIds: tokenIds,
                     tierIds: tierIdsToMint,
-                    beneficiary: context.beneficiary,
+                    beneficiary: beneficiary,
                     totalAmountPaid: totalAmountPaid
                 });
             }
@@ -714,19 +735,19 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
                 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;
+            payCreditsOf[beneficiary] = newPayCredits;
         }
     }
 
@@ -749,11 +770,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 +796,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 +813,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 +855,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});
     }
 }

package/src/abstract/JB721Hook.sol

@@ -77,6 +77,7 @@ abstract contract JB721Hook is ERC721, IJB721Hook {
     /// @return cashOutTaxRate The cash out tax rate influencing the reclaim amount.
     /// @return cashOutCount The amount of tokens that should be considered cashed out.
     /// @return totalSupply The total amount of tokens that are considered to be existing.
+    /// @return effectiveSurplusValue The surplus to use for reclaim calculation.
     /// @return hookSpecifications The amount and data to send to cash out hooks (this contract) instead of returning to
     /// the beneficiary.
     function beforeCashOutRecordedWith(JBBeforeCashOutRecordedContext calldata context)
@@ -88,6 +89,7 @@ abstract contract JB721Hook is ERC721, IJB721Hook {
             uint256 cashOutTaxRate,
             uint256 cashOutCount,
             uint256 totalSupply,
+            uint256 effectiveSurplusValue,
             JBCashOutHookSpecification[] memory hookSpecifications
         )
     {
@@ -114,6 +116,9 @@ abstract contract JB721Hook is ERC721, IJB721Hook {
         // Use the total cash out weight of the 721s.
         totalSupply = totalCashOutWeight();
 
+        // Use the surplus from the context.
+        effectiveSurplusValue = context.surplus.value;
+
         // Use the cash out tax rate from the context.
         cashOutTaxRate = context.cashOutTaxRate;
     }

package/src/interfaces/IJB721Checkpoints.sol

@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+import {IERC5805} from "@openzeppelin/contracts/interfaces/IERC5805.sol";
+import {IJB721TiersHookStore} from "./IJB721TiersHookStore.sol";
+
+/// @notice A checkpoint module that provides IVotes-compatible checkpointed voting power for a JB721TiersHook.
+/// @dev Deployed as a clone via JB721CheckpointsDeployer during hook initialization. One module per hook.
+/// Pass this address to JBTokenDistributor as the IVotes token.
+interface IJB721Checkpoints is IERC5805 {
+    /// @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.
+    /// Auto-self-delegates on first receive so checkpoints work without manual delegation.
+    /// @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 (used to look up tier voting units).
+    function onTransfer(address from, address to, uint256 tokenId) external;
+
+    /// @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;
+
+    /// @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);
+
+    /// @notice The store that holds tier and voting data for the hook's NFTs.
+    /// @return The store contract.
+    // forge-lint: disable-next-line(mixed-case-function)
+    function STORE() external view returns (IJB721TiersHookStore);
+}

package/src/interfaces/IJB721CheckpointsDeployer.sol

@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+import {IJB721Checkpoints} from "./IJB721Checkpoints.sol";
+import {IJB721TiersHookStore} from "./IJB721TiersHookStore.sol";
+
+/// @notice Deploys JB721Checkpoints clones for JB721TiersHook instances.
+interface IJB721CheckpointsDeployer {
+    /// @notice The implementation contract that clones are based on.
+    /// @return The implementation address.
+    // forge-lint: disable-next-line(mixed-case-function)
+    function IMPLEMENTATION() external view returns (address);
+
+    /// @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 returns (IJB721Checkpoints module);
+}