@bananapus/721-hook-v6 0.0.61 → 0.0.63

package/README.md

@@ -34,6 +34,7 @@ This repo does more than "mint NFTs on pay." It changes how payment value, tier
 | `JB721TiersHookDeployer` | Clone factory for deploying a hook for an existing project. |
 | `JB721TiersHookProjectDeployer` | Convenience deployer for launching a project with a hook already wired in. |
 | `JB721Hook` | Abstract base for 721 pay and cash-out hook behavior. |
+| `JB721Checkpoints` | Per-hook IVotes checkpoint module. Tracks historical owner checkpoints plus per-tier eligible voting units (`getPastTierVotingUnits`) for tier-scoped reward distribution. |
 
 ## Mental Model
 
@@ -59,6 +60,7 @@ If a bug affects supply, reserve minting, or tier lookup, it usually lives in th
 - custom token URI resolvers should be treated as part of the trusted surface
 - adding a 721 hook through a deployer is easy; carrying the right ruleset behavior forward is where mistakes happen
 - projects should be explicit about whether the hook affects pay, cash out, or only metadata-facing paths
+- per-tier eligible voting units are queryable via `getPastTierVotingUnits(tierId, blockNumber)` for tier-scoped reward denominators, but minting alone does not enroll a token: a token only counts toward that total once it is enrolled (`delegate(address, uint256[])`) or transferred for the first time, and stops counting when burned
 
 ## Where State Lives
 

package/package.json

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

package/references/operations.md

@@ -12,6 +12,7 @@
 - If you edit tier config or metadata behavior, inspect the corresponding structs and interfaces in `src/structs/` and `src/interfaces/`.
 - If you edit reserve behavior, verify pending reserve counts, default reserve beneficiary semantics, and cash-out denominator effects together.
 - If you edit discount behavior, verify mint price and cash-out weight separately. They are intentionally not the same quantity.
+- If you touch checkpoint, `onTransfer`, or `delegate` behavior, verify the per-tier eligible-voting-units trace (`_tierEligibleUnitsOf`, read via `getPastTierVotingUnits`) still moves only on eligibility changes: increment on enrollment or a token's first transfer, decrement on burn, and nothing on mint (so the mint path keeps its zero added checkpoint gas). Keep it in lockstep with `ownerOfAt` eligibility.
 - If you touch permissions, verify the caller path and permission constants still line up with the downstream ecosystem package that defines them.
 - If you touch URI behavior, confirm whether the issue belongs in this repo or in a downstream resolver contract that the hook calls.
 

package/src/JB721Checkpoints.sol

@@ -50,6 +50,12 @@ contract JB721Checkpoints is Votes, IJB721Checkpoints {
     /// @custom:param tokenId The token ID to get historical owner checkpoints for.
     mapping(uint256 tokenId => Checkpoints.Trace160) internal _ownerCheckpointsOf;
 
+    /// @notice Checkpointed total eligible voting units per tier. A token contributes its tier voting units from the
+    /// block it first gains an owner checkpoint (enrollment or first transfer) until it is burned. Mints write
+    /// nothing, mirroring `_ownerCheckpointsOf` eligibility. Distributors read this as the tier-scoped denominator.
+    /// @custom:param tierId The tier to get the historical eligible voting units for.
+    mapping(uint256 tierId => Checkpoints.Trace160) internal _tierEligibleUnitsOf;
+
     //*********************************************************************//
     // -------------------------- constructor ---------------------------- //
     //*********************************************************************//
@@ -85,10 +91,15 @@ contract JB721Checkpoints is Votes, IJB721Checkpoints {
                 revert JB721Checkpoints_NotOwner({tokenId: tokenId, caller: msg.sender});
             }
 
-            // Write an owner checkpoint if the token has none yet.
+            // Write an owner checkpoint if the token has none yet, and enroll its tier voting units.
             if (_ownerCheckpointsOf[tokenId].length() == 0) {
                 // forge-lint: disable-next-line(unsafe-typecast)
                 _ownerCheckpointsOf[tokenId].push({key: uint96(block.number), value: uint160(msg.sender)});
+                _updateTierEligibleUnits({
+                    tierId: STORE.tierIdOfToken(tokenId),
+                    amount: STORE.tierVotingUnitsOfTokenId({hook: hook, tokenId: tokenId}),
+                    increase: true
+                });
             }
 
             unchecked {
@@ -114,14 +125,31 @@ contract JB721Checkpoints is Votes, IJB721Checkpoints {
     function onTransfer(address from, address to, uint256 tokenId) external override {
         if (msg.sender != hook) revert JB721Checkpoints_Unauthorized({caller: msg.sender, hook: hook});
 
+        // Look up this token's tier voting units (lightweight getter — avoids full tier struct construction).
+        uint256 votingUnits = STORE.tierVotingUnitsOfTokenId({hook: hook, tokenId: tokenId});
+
+        // On mint (`from == 0`) nothing is checkpointed: the token is ineligible until enrolled or transferred,
+        // so neither the owner trace nor the per-tier eligible-units trace is written.
         if (from != address(0)) {
+            Checkpoints.Trace160 storage ownerTrace = _ownerCheckpointsOf[tokenId];
+            bool wasEligible = ownerTrace.length() != 0;
+
             // forge-lint: disable-next-line(unsafe-typecast)
-            _ownerCheckpointsOf[tokenId].push({key: uint96(block.number), value: uint160(to)});
+            ownerTrace.push({key: uint96(block.number), value: uint160(to)});
+
+            if (to == address(0)) {
+                // Burn: remove the tier's units only if the token was already eligible.
+                if (wasEligible) {
+                    _updateTierEligibleUnits({
+                        tierId: STORE.tierIdOfToken(tokenId), amount: votingUnits, increase: false
+                    });
+                }
+            } else if (!wasEligible) {
+                // First transfer of a never-enrolled token makes it eligible: add the tier's units.
+                _updateTierEligibleUnits({tierId: STORE.tierIdOfToken(tokenId), amount: votingUnits, increase: true});
+            }
         }
 
-        // 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});
     }
@@ -130,6 +158,12 @@ contract JB721Checkpoints is Votes, IJB721Checkpoints {
     // ----------------------- external views ---------------------------- //
     //*********************************************************************//
 
+    /// @inheritdoc IJB721Checkpoints
+    function getPastTierVotingUnits(uint256 tierId, uint256 blockNumber) external view override returns (uint256) {
+        // forge-lint: disable-next-line(unsafe-typecast)
+        return _tierEligibleUnitsOf[tierId].upperLookupRecent(uint96(_validateTimepoint(blockNumber)));
+    }
+
     /// @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
     /// transferred. Unenrolled tokens are ineligible for snapshot-based distribution.
@@ -163,4 +197,19 @@ contract JB721Checkpoints is Votes, IJB721Checkpoints {
     function _getVotingUnits(address account) internal view override returns (uint256) {
         return STORE.votingUnitsOf({hook: hook, account: account});
     }
+
+    //*********************************************************************//
+    // ------------------------ private helpers -------------------------- //
+    //*********************************************************************//
+
+    /// @notice Add or remove units from a tier's eligible-voting-units checkpoint at the current block.
+    /// @param tierId The tier whose eligible-voting-units trace to update.
+    /// @param amount The voting units to add or remove.
+    /// @param increase Whether to add `amount`; if false, `amount` is removed.
+    function _updateTierEligibleUnits(uint256 tierId, uint256 amount, bool increase) private {
+        Checkpoints.Trace160 storage trace = _tierEligibleUnitsOf[tierId];
+        uint256 updated = increase ? trace.latest() + amount : trace.latest() - amount;
+        // forge-lint: disable-next-line(unsafe-typecast)
+        trace.push({key: uint96(block.number), value: uint160(updated)});
+    }
 }

package/src/JB721TiersHookStore.sol

@@ -261,6 +261,24 @@ contract JB721TiersHookStore is IJB721TiersHookStore {
         transfersPausable = (storedTier.packedBools & 0x2) != 0;
     }
 
+    /// @notice Get only the per-unit voting value for a token's tier, avoiding full struct construction.
+    /// @dev Mirrors the `votingUnits` field computed in `_getTierFrom`: a tier with custom voting units configured
+    /// (the `useVotingUnits` flag, bit 2 of `packedBools`) contributes its stored voting units per NFT, otherwise it
+    /// contributes its price per NFT. Multiply by an account's balance in the tier to get its voting power there.
+    /// @param hook The 721 hook contract that the token belongs to.
+    /// @param tokenId The token ID.
+    /// @return The per-unit voting value for the token's tier.
+    function tierVotingUnitsOfTokenId(address hook, uint256 tokenId) external view override returns (uint256) {
+        // Get a reference to the tier's ID.
+        uint256 tierId = tierIdOfToken(tokenId);
+
+        // Keep a reference to the stored tier.
+        JBStored721Tier memory storedTier = _storedTierOf[hook][tierId];
+
+        // Bit 2 (0-indexed) of packedBools is useVotingUnits. Use custom voting units if set, otherwise the price.
+        return (storedTier.packedBools & 0x4 != 0) ? _tierVotingUnitsOf[hook][tierId] : storedTier.price;
+    }
+
     /// @notice Get all active (non-removed) tiers for a hook, with optional filtering by category and pagination.
     /// Tiers are returned sorted by category.
     /// @param hook The 721 hook contract to get tiers from.

package/src/interfaces/IJB721Checkpoints.sol

@@ -8,6 +8,15 @@ import {IJB721TiersHookStore} from "./IJB721TiersHookStore.sol";
 /// @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 The total eligible voting units of a tier at a past block.
+    /// @dev "Eligible" means a token has an owner checkpoint: it was enrolled via `delegate(address,uint256[])` or
+    /// transferred at least once. Minted-but-unenrolled tokens are excluded, mirroring `ownerOfAt` eligibility, and
+    /// mints never write to this trace. Distributors use this as the denominator for tier-scoped reward pots.
+    /// @param tierId The tier to get the eligible voting units of.
+    /// @param blockNumber The block number to look up (must be strictly in the past).
+    /// @return The tier's eligible voting units at `blockNumber`.
+    function getPastTierVotingUnits(uint256 tierId, uint256 blockNumber) external view returns (uint256);
+
     /// @notice The hook that this module tracks voting power for.
     /// @return The hook address.
     // forge-lint: disable-next-line(mixed-case-function)

package/src/interfaces/IJB721TiersHookStore.sol

@@ -151,6 +151,12 @@ interface IJB721TiersHookStore {
         view
         returns (uint256 tierId, bool transfersPausable);
 
+    /// @notice Get only the per-unit voting value for a token's tier, avoiding full struct construction.
+    /// @param hook The 721 hook address.
+    /// @param tokenId The token ID.
+    /// @return The per-unit voting value for the token's tier (custom voting units if set, otherwise the tier price).
+    function tierVotingUnitsOfTokenId(address hook, uint256 tokenId) external view returns (uint256);
+
     /// @notice Get an array of currently active 721 tiers for the provided 721 contract.
     /// @param hook The 721 contract to get the tiers of.
     /// @param categories An array of tier categories to get tiers from. Empty for all categories.