@bananapus/721-hook-v6 0.0.32 → 0.0.34

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);
+}

package/src/interfaces/IJB721TiersHook.sol

@@ -6,6 +6,8 @@ import {IJBRulesets} from "@bananapus/core-v6/src/interfaces/IJBRulesets.sol";
 import {IJBSplits} from "@bananapus/core-v6/src/interfaces/IJBSplits.sol";
 import {JBSplit} from "@bananapus/core-v6/src/structs/JBSplit.sol";
 
+import {IJB721Checkpoints} from "./IJB721Checkpoints.sol";
+import {IJB721CheckpointsDeployer} from "./IJB721CheckpointsDeployer.sol";
 import {IJB721Hook} from "./IJB721Hook.sol";
 import {IJB721TiersHookStore} from "./IJB721TiersHookStore.sol";
 import {IJB721TokenUriResolver} from "./IJB721TokenUriResolver.sol";
@@ -144,6 +146,12 @@ interface IJB721TiersHook is IJB721Hook {
     /// @return decimals The amount of decimals being used in tier prices.
     function pricingContext() external view returns (uint256 currency, uint256 decimals);
 
+    /// @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);
+
     /// @notice The contract that exposes price feeds for currency conversions.
     /// @return The prices contract.
     function PRICES() external view returns (IJBPrices);

package/src/libraries/JB721Constants.sol

@@ -4,4 +4,10 @@ pragma solidity 0.8.28;
 /// @notice Global constants used across 721 hook contracts.
 library JB721Constants {
     uint16 public constant DISCOUNT_DENOMINATOR = 200;
+
+    /// @notice The metadata ID used to identify the 721 beneficiary entry in payment metadata.
+    /// @dev When a sucker pays on behalf of a remote user, the real user's address is embedded under this key
+    /// so NFTs mint to the correct recipient.
+    // forge-lint: disable-next-line(mixed-case-variable)
+    bytes4 public constant BENEFICIARY_METADATA_ID = bytes4(keccak256("JB_721_BENEFICIARY"));
 }