@bananapus/721-hook-v6 0.0.70 → 0.0.73

package/README.md

@@ -10,7 +10,7 @@
 - [AUDIT_INSTRUCTIONS.md](./AUDIT_INSTRUCTIONS.md) — what to focus on for a security audit and how to start.
 - [SKILLS.md](./SKILLS.md) — implementation nuances, gotchas, and reading order for working on this codebase.
 - [STYLE_GUIDE.md](./STYLE_GUIDE.md) — Solidity conventions and repo layout used across the V6 ecosystem.
-- [CHANGELOG.md](./CHANGELOG.md) — v5 → v6 ABI and behavior deltas.
+- [CHANGELOG.md](./CHANGELOG.md) - V5 to V6 ABI and behavior deltas.
 - [references/runtime.md](./references/runtime.md) — contract roles, the runtime pay and cash-out path, and high-risk areas.
 - [references/operations.md](./references/operations.md) — deployment surface, change checklist, and common failure modes.
 
@@ -38,7 +38,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, per-tier eligible voting units (`getPastTierVotingUnits`) for tier-scoped reward distribution, and active delegated vote totals (`getPastTotalActiveVotes`). |
+| `JB721Checkpoints` | Per-hook IVotes checkpoint module. Tracks historical owner checkpoints, per-tier owner-tracked voting units (`getPastTierVotingUnits`), global active vote totals (`getPastTotalActiveVotes`), per-tier active vote totals (`getPastTotalTierActiveVotes`), and per-account active tier voting units (`getPastAccountTierActiveVotes`). |
 
 ## Mental model
 
@@ -64,8 +64,9 @@ 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
-- active delegated vote totals are queryable via `getPastTotalActiveVotes(blockNumber)` and `getTotalActiveVotes()`. These totals include only voting units held by accounts with a nonzero delegate, so a token in undelegated custody does not count; this is a governance/reward-participation primitive, not the owner-based tier reward denominator.
+- per-tier owner-tracked voting units are queryable via `getPastTierVotingUnits(tierId, blockNumber)`: mints, transfers, and burns write ownership history, so the trace follows owned units regardless of delegation
+- active delegated vote totals are queryable globally via `getPastTotalActiveVotes(blockNumber)` / `getTotalActiveVotes()` and per tier via `getPastTotalTierActiveVotes(tierId, blockNumber)` / `getTotalTierActiveVotes(tierId)`. These totals include only voting units held by accounts with a nonzero delegate, so a token in undelegated custody does not count and returned tokens become active again if the holder's delegation is still set.
+- per-account active tier voting units are queryable via `getPastAccountTierActiveVotes(account, tierId, blockNumber)`. This follows the account holding the tier units, not the delegate receiving voting power, so reward distributors can cap tier-scoped claims against the holder's active units even when votes are delegated to another address.
 
 ## Where state lives
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/721-hook-v6",
-  "version": "0.0.70",
+  "version": "0.0.73",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -25,12 +25,12 @@
     "artifacts": "source ./.env && npx sphinx artifacts --org-id 'ea165b21-7cdc-4d7b-be59-ecdd4c26bee4' --project-name 'nana-721-hook-v6'"
   },
   "dependencies": {
-    "@bananapus/address-registry-v6": "^0.0.33",
-    "@bananapus/core-v6": "^0.0.85",
-    "@bananapus/ownable-v6": "^0.0.36",
-    "@bananapus/permission-ids-v6": "^0.0.29",
+    "@bananapus/address-registry-v6": "^0.0.34",
+    "@bananapus/core-v6": "^0.0.86",
+    "@bananapus/ownable-v6": "^0.0.37",
+    "@bananapus/permission-ids-v6": "^0.0.30",
     "@openzeppelin/contracts": "5.6.1",
-    "@prb/math": "4.1.1",
+    "@prb/math": "4.1.2",
     "solady": "0.1.26"
   },
   "devDependencies": {

package/references/operations.md

@@ -12,8 +12,8 @@
 - 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.
-- Also verify the active delegated vote trace (`_activeSupplyCheckpoints`, read via `getPastTotalActiveVotes` and `getTotalActiveVotes`) moves only when voting units enter or leave nonzero delegation. It is separate from owner-based tier reward eligibility.
+- 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 mint or first checkpoint backfill, decrement on burn, and stay unchanged on ordinary transfers. Keep it in lockstep with `ownerOfAt` eligibility.
+- Also verify the active delegated vote traces (`_activeSupplyCheckpoints`, `_tierActiveSupplyCheckpointsOf`, and `_accountTierActiveVotesOf`) move only when voting units enter or leave nonzero delegation. They are separate from owner-based tier reward 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

@@ -29,7 +29,7 @@ contract JB721Checkpoints is Votes, IJB721Checkpoints {
     /// @notice Thrown when `initialize` is called on a module whose hook has already been set.
     error JB721Checkpoints_AlreadyInitialized(address hook);
 
-    /// @notice Thrown when the caller tries to enroll a token they do not currently own.
+    /// @notice Thrown when the caller tries to backfill a token they do not currently own.
     error JB721Checkpoints_NotOwner(uint256 tokenId, address caller);
 
     /// @notice Thrown when a hook-only function is called by an address other than the module's hook.
@@ -40,6 +40,7 @@ contract JB721Checkpoints is Votes, IJB721Checkpoints {
     //*********************************************************************//
 
     /// @notice The store that holds tier and voting data for the hook's NFTs.
+    /// @dev All tier lookups are scoped by `hook`; this immutable only identifies the shared store contract.
     IJB721TiersHookStore public immutable override STORE;
 
     //*********************************************************************//
@@ -47,33 +48,50 @@ contract JB721Checkpoints is Votes, IJB721Checkpoints {
     //*********************************************************************//
 
     /// @notice The hook that this module tracks voting power for.
+    /// @dev Clones set this once in `initialize`; the implementation uses `address(1)` as a locked sentinel.
     address public override hook;
 
     //*********************************************************************//
     // -------------------- internal stored properties ------------------- //
     //*********************************************************************//
 
-    /// @notice Checkpointed token owners for historical reward eligibility. Written on enrollment or transfer.
+    /// @notice Checkpointed active voting units per account and tier.
+    /// @dev Maintained only for units held by accounts with nonzero delegates. Undelegated custody is not checkpointed
+    /// in this trace because those units are inactive for active-vote reward accounting.
+    /// @custom:param account The account to get historical active tier voting units for.
+    /// @custom:param tierId The tier to get historical active voting units for.
+    mapping(address account => mapping(uint256 tierId => Checkpoints.Trace160)) internal _accountTierActiveVotesOf;
+
+    /// @notice Checkpointed token owners for historical reward eligibility.
+    /// @dev Mint and transfer hooks write this automatically; `delegate` only backfills missing pre-upgrade history.
     /// @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.
+    /// @notice Checkpointed total active voting units per tier.
+    /// @dev Maintained when delegation changes activate/deactivate all of an account's tier units, and when transfers
+    /// move one token's tier units between delegated and undelegated custody.
+    /// @custom:param tierId The tier to get the historical delegated voting units for.
+    mapping(uint256 tierId => Checkpoints.Trace160) internal _tierActiveSupplyCheckpointsOf;
+
+    /// @notice Checkpointed total owner-tracked voting units per tier.
+    /// @dev Increased on mint or backfill and decreased on burn. Transfers keep the total unchanged because the token
+    /// still has a nonzero owner.
+    /// @custom:param tierId The tier to get the historical owner-tracked voting units for.
     mapping(uint256 tierId => Checkpoints.Trace160) internal _tierEligibleUnitsOf;
 
     //*********************************************************************//
     // -------------------- private stored properties -------------------- //
     //*********************************************************************//
 
-    /// @notice The total voting units currently delegated to nonzero delegates.
+    /// @notice Checkpointed total voting units held by accounts with nonzero delegates.
+    /// @dev Maintained by `_delegate` and `_transferVotingUnits` using the same clock as OZ `Votes`.
     Checkpoints.Trace208 private _activeSupplyCheckpoints;
 
     //*********************************************************************//
     // -------------------------- constructor ---------------------------- //
     //*********************************************************************//
 
+    /// @notice Initializes the checkpoint implementation and locks it against direct use.
     /// @dev The implementation contract is initialized in the constructor to prevent direct use. Clones are initialized
     /// via `initialize()`.
     /// @param store The store that holds tier data for each hook's NFTs.
@@ -86,26 +104,25 @@ contract JB721Checkpoints is Votes, IJB721Checkpoints {
     // ---------------------- external transactions ---------------------- //
     //*********************************************************************//
 
-    /// @notice Delegates voting power and enrolls tokens for distribution eligibility.
-    /// @dev Writes per-token owner checkpoints so `ownerOfAt` can prove ownership at past blocks.
-    /// Only the current token owner can enroll. Tokens without checkpoints are ineligible for snapshot-based
-    /// distribution. The existing `delegate(address)` from OZ Votes still works for pure delegation without enrollment.
+    /// @notice Delegates voting power and backfills ownership history for listed tokens if needed.
+    /// @dev Mint and transfer hooks normally write owner checkpoints automatically. The token ID list keeps
+    /// pre-upgrade or otherwise uncheckpointed tokens recoverable while preserving the owner-only authorization check.
     /// @param delegatee The address to delegate voting power to. Use your own address for self-delegation.
-    /// @param tokenIds The token IDs to enroll for distribution eligibility.
+    /// @param tokenIds The token IDs whose owner checkpoints should be backfilled if missing.
     function delegate(address delegatee, uint256[] calldata tokenIds) external override {
         // Delegate voting power (reuses OZ Votes internals).
         _delegate({account: msg.sender, delegatee: delegatee});
 
-        // Write per-token owner checkpoints for distribution eligibility.
+        // Write any missing per-token owner checkpoints for historical reward eligibility.
         for (uint256 i; i < tokenIds.length;) {
             uint256 tokenId = tokenIds[i];
 
-            // Only the current owner can enroll their tokens.
+            // Only the current owner can backfill their token's ownership checkpoint.
             if (IERC721(hook).ownerOf(tokenId) != msg.sender) {
                 revert JB721Checkpoints_NotOwner({tokenId: tokenId, caller: msg.sender});
             }
 
-            // Write an owner checkpoint if the token has none yet, and enroll its tier voting units.
+            // Write an owner checkpoint if the token has none yet, and track 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)});
@@ -139,54 +156,129 @@ 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 ID and voting units once; both the owner and active traces need them.
+        uint256 tierId = STORE.tierIdOfToken(tokenId);
+
         // 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;
+        // Keep a reference to the token's historical owner trace.
+        Checkpoints.Trace160 storage ownerTrace = _ownerCheckpointsOf[tokenId];
+
+        // Existing deployments may have tokens that predate mint checkpointing; detect the first written owner.
+        bool wasEligible = ownerTrace.length() != 0;
 
+        // Mints, transfers, and burns all write ownership history so reward claims can prove snapshot ownership.
+        if (to != address(0) || from != address(0)) {
             // forge-lint: disable-next-line(unsafe-typecast)
             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});
+        if (from == address(0) && to != address(0)) {
+            // Mint: add the token's tier units to the owner-tracked tier supply.
+            _updateTierEligibleUnits({tierId: tierId, amount: votingUnits, increase: true});
+        } else if (to == address(0)) {
+            // Burn: remove the tier's units only if the token was already part of the owner-tracked supply.
+            if (wasEligible) {
+                _updateTierEligibleUnits({tierId: tierId, amount: votingUnits, increase: false});
             }
+        } else if (!wasEligible) {
+            // First transfer of a pre-upgrade uncheckpointed token makes its ownership history trackable.
+            _updateTierEligibleUnits({tierId: tierId, amount: votingUnits, increase: true});
         }
 
+        // The tier active total decreases if units leave an account that already has a nonzero delegate.
+        bool decreaseTierActiveVotes = from != address(0) && delegates(from) != address(0);
+
+        // The tier active total increases if units arrive at an account that already has a nonzero delegate.
+        bool increaseTierActiveVotes = to != address(0) && delegates(to) != address(0);
+
         // Move checkpointed voting power from the previous owner to the new owner.
         _transferVotingUnits({from: from, to: to, amount: votingUnits});
+
+        // If the sender was delegated, remove this token's tier units from the sender's active tier balance.
+        if (decreaseTierActiveVotes) {
+            _adjustAccountTierActiveVotes({account: from, tierId: tierId, amount: votingUnits, increase: false});
+        }
+
+        // If the receiver is delegated, add this token's tier units to the receiver's active tier balance.
+        if (increaseTierActiveVotes) {
+            _adjustAccountTierActiveVotes({account: to, tierId: tierId, amount: votingUnits, increase: true});
+        }
+
+        // If both sides are delegated or both sides are undelegated, this tier's active total is unchanged.
+        if (decreaseTierActiveVotes != increaseTierActiveVotes) {
+            // Otherwise apply the one-sided active-tier delta implied by the receiver's delegated status.
+            _adjustTotalTierActiveVotes({tierId: tierId, amount: votingUnits, increase: increaseTierActiveVotes});
+        }
     }
 
     //*********************************************************************//
     // ----------------------- external views ---------------------------- //
     //*********************************************************************//
 
-    /// @notice The total eligible voting units of a tier at a past block.
-    /// @param tierId The tier to get the eligible voting units of.
+    /// @notice The delegated voting units held by an account in a tier at a past block.
+    /// @dev Counts only tier voting units held by `account` while `account` had a nonzero delegate.
+    /// @param account The account to get the delegated tier voting units of.
+    /// @param tierId The tier to get the delegated voting units of.
+    /// @param blockNumber The past block number to look up.
+    /// @return activeVotes The account's delegated tier voting units at `blockNumber`.
+    function getPastAccountTierActiveVotes(
+        address account,
+        uint256 tierId,
+        uint256 blockNumber
+    )
+        external
+        view
+        override
+        returns (uint256 activeVotes)
+    {
+        // forge-lint: disable-next-line(unsafe-typecast)
+        activeVotes =
+            _accountTierActiveVotesOf[account][tierId].upperLookupRecent(uint96(_validateTimepoint(blockNumber)));
+    }
+
+    /// @notice The total owner-checkpointed voting units of a tier at a past block.
+    /// @param tierId The tier to get the owner-checkpointed 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 override returns (uint256) {
+    /// @return votingUnits The tier's owner-checkpointed voting units at `blockNumber`.
+    function getPastTierVotingUnits(
+        uint256 tierId,
+        uint256 blockNumber
+    )
+        external
+        view
+        override
+        returns (uint256 votingUnits)
+    {
         // forge-lint: disable-next-line(unsafe-typecast)
-        return _tierEligibleUnitsOf[tierId].upperLookupRecent(uint96(_validateTimepoint(blockNumber)));
+        votingUnits = _tierEligibleUnitsOf[tierId].upperLookupRecent(uint96(_validateTimepoint(blockNumber)));
     }
 
     /// @notice The total delegated voting units at a past block.
     /// @dev This tracks delegated vote participation and is separate from tier reward eligibility.
-    /// @param timepoint The past block number to look up.
-    /// @return activeVotes The total voting units delegated to nonzero delegates at `timepoint`.
-    function getPastTotalActiveVotes(uint256 timepoint) external view override returns (uint256 activeVotes) {
-        activeVotes = _activeSupplyCheckpoints.upperLookupRecent(_validateTimepoint(timepoint));
+    /// @param blockNumber The past block number to look up.
+    /// @return activeVotes The total voting units delegated to nonzero delegates at `blockNumber`.
+    function getPastTotalActiveVotes(uint256 blockNumber) external view override returns (uint256 activeVotes) {
+        activeVotes = _activeSupplyCheckpoints.upperLookupRecent(_validateTimepoint(blockNumber));
+    }
+
+    /// @notice The total delegated voting units of a tier at a past block.
+    /// @dev Counts only tier voting units held by accounts with a nonzero delegate.
+    /// @param tierId The tier to get the delegated voting units of.
+    /// @param blockNumber The past block number to look up.
+    /// @return activeVotes The tier's delegated voting units at `blockNumber`.
+    function getPastTotalTierActiveVotes(
+        uint256 tierId,
+        uint256 blockNumber
+    )
+        external
+        view
+        override
+        returns (uint256 activeVotes)
+    {
+        // forge-lint: disable-next-line(unsafe-typecast)
+        activeVotes = _tierActiveSupplyCheckpointsOf[tierId].upperLookupRecent(uint96(_validateTimepoint(blockNumber)));
     }
 
     /// @notice The current total delegated voting units.
@@ -196,23 +288,29 @@ contract JB721Checkpoints is Votes, IJB721Checkpoints {
         activeVotes = _activeSupplyCheckpoints.latest();
     }
 
+    /// @notice The current total delegated voting units of a tier.
+    /// @param tierId The tier to get the current delegated voting units of.
+    /// @return activeVotes The tier's current delegated voting units.
+    function getTotalTierActiveVotes(uint256 tierId) external view override returns (uint256 activeVotes) {
+        activeVotes = _tierActiveSupplyCheckpointsOf[tierId].latest();
+    }
+
     /// @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.
+    /// @dev Returns `address(0)` if no ownership checkpoint exists or the query predates the first checkpoint.
     /// @param tokenId The token ID of the NFT to get the historical owner of.
     /// @param blockNumber The block number to look up.
-    /// @return The owner of the token at `blockNumber`, or zero if the token is unenrolled or has no known owner.
-    function ownerOfAt(uint256 tokenId, uint256 blockNumber) external view override returns (address) {
+    /// @return owner The owner of the token at `blockNumber`, or zero if no owner is proven at that block.
+    function ownerOfAt(uint256 tokenId, uint256 blockNumber) external view override returns (address owner) {
         // forge-lint: disable-next-line(unsafe-typecast)
         uint96 blockNumber96 = uint96(blockNumber);
 
         Checkpoints.Trace160 storage checkpoints = _ownerCheckpointsOf[tokenId];
         uint256 checkpointCount = checkpoints.length();
 
-        // No checkpoints = not enrolled and never transferred. Not eligible.
+        // No checkpoints means no historical owner can be proven for this token.
         if (checkpointCount == 0) return address(0);
 
-        // Query is before the first checkpoint — token not yet enrolled/transferred at this block.
+        // Query is before the first checkpoint, so this token had no proven owner at that block.
         if (checkpoints.at(0)._key > blockNumber96) return address(0);
 
         return address(uint160(checkpoints.upperLookupRecent(blockNumber96)));
@@ -242,9 +340,15 @@ contract JB721Checkpoints is Votes, IJB721Checkpoints {
         if (oldDelegate == address(0) && delegatee != address(0)) {
             // Add the account's voting units to the checkpointed active total.
             _updateActiveVotes({amount: votingUnits, increase: true});
+
+            // Add the account's voting units to each tier-level active total it currently contributes to.
+            _applyAccountDelegationToTierActiveVotes({account: account, increase: true});
         } else if (oldDelegate != address(0) && delegatee == address(0)) {
             // If the account had a delegate and now has none, its voting units just became inactive.
             _updateActiveVotes({amount: votingUnits, increase: false});
+
+            // Remove the account's voting units from each tier-level active total it currently contributes to.
+            _applyAccountDelegationToTierActiveVotes({account: account, increase: false});
         }
     }
 
@@ -279,8 +383,8 @@ contract JB721Checkpoints is Votes, IJB721Checkpoints {
     /// @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 votingUnits The total voting units the account holds.
+    function _getVotingUnits(address account) internal view override returns (uint256 votingUnits) {
         return STORE.votingUnitsOf({hook: hook, account: account});
     }
 
@@ -288,6 +392,74 @@ contract JB721Checkpoints is Votes, IJB721Checkpoints {
     // ------------------------ private helpers -------------------------- //
     //*********************************************************************//
 
+    /// @notice Add or remove units from an account's active-voting-units checkpoint for a tier at the current block.
+    /// @param account The account whose active-voting-units trace should be updated.
+    /// @param tierId The tier whose active-voting-units trace should be updated.
+    /// @param amount The voting units to add or remove.
+    /// @param increase Whether to add `amount`; if false, `amount` is removed.
+    function _adjustAccountTierActiveVotes(address account, uint256 tierId, uint256 amount, bool increase) private {
+        // Ignore zero-unit updates because they do not change the account's active tier total.
+        if (amount == 0) return;
+
+        // Keep a reference to the account's active-voting-units trace for this tier.
+        Checkpoints.Trace160 storage trace = _accountTierActiveVotesOf[account][tierId];
+
+        // Calculate the next account-tier active total from its latest checkpointed value.
+        uint256 updated = increase ? trace.latest() + amount : trace.latest() - amount;
+
+        // Write the new account-tier active total at the current block.
+        // forge-lint: disable-next-line(unsafe-typecast)
+        trace.push({key: uint96(block.number), value: uint160(updated)});
+    }
+
+    /// @notice Add or remove units from a tier's active-voting-units checkpoint at the current block.
+    /// @param tierId The tier whose active-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 _adjustTotalTierActiveVotes(uint256 tierId, uint256 amount, bool increase) private {
+        // Ignore zero-unit updates because they do not change this tier's active total.
+        if (amount == 0) return;
+
+        // Keep a reference to the tier's active-voting-units trace.
+        Checkpoints.Trace160 storage trace = _tierActiveSupplyCheckpointsOf[tierId];
+
+        // Calculate the next tier active total by adding or subtracting from the latest checkpointed value.
+        uint256 updated = increase ? trace.latest() + amount : trace.latest() - amount;
+
+        // Write the new tier active total at the current block.
+        // forge-lint: disable-next-line(unsafe-typecast)
+        trace.push({key: uint96(block.number), value: uint160(updated)});
+    }
+
+    /// @notice Apply an account delegation change to every tier-level active total the account contributes to.
+    /// @dev Delegation is account-wide in OZ Votes, so changing an account's delegate activates or deactivates every
+    /// tier balance currently held by the account. Transfer hooks handle one-token tier deltas separately.
+    /// @param account The account whose tier voting units should be added or removed.
+    /// @param increase Whether to add `account`'s tier voting units; if false, they are removed.
+    function _applyAccountDelegationToTierActiveVotes(address account, bool increase) private {
+        // Read the largest tier ID once; tier IDs are sequential and 1-indexed for each hook.
+        uint256 tierId = STORE.maxTierIdOf(hook);
+
+        // Walk each tier from max to 1 so empty hooks skip cleanly when maxTierId is zero.
+        while (tierId != 0) {
+            // Read only this account's units for the tier; empty tiers return zero and are ignored below.
+            uint256 tierVotingUnits = STORE.tierVotingUnitsOf({hook: hook, account: account, tierId: tierId});
+
+            // Only write checkpoints for tiers whose active totals actually change.
+            if (tierVotingUnits != 0) {
+                _adjustTotalTierActiveVotes({tierId: tierId, amount: tierVotingUnits, increase: increase});
+                _adjustAccountTierActiveVotes({
+                    account: account, tierId: tierId, amount: tierVotingUnits, increase: increase
+                });
+            }
+
+            unchecked {
+                // The loop condition proves tierId is nonzero, so the decrement cannot underflow.
+                --tierId;
+            }
+        }
+    }
+
     /// @notice Update the checkpointed total of delegated voting units.
     /// @dev Writes at most one active-total checkpoint at the current OZ clock. A zero amount is ignored so zero-value
     /// delegation or transfer hooks do not create empty checkpoints.
@@ -305,13 +477,21 @@ contract JB721Checkpoints is Votes, IJB721Checkpoints {
         _activeSupplyCheckpoints.push({key: clock(), value: SafeCast.toUint208(updated)});
     }
 
-    /// @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.
+    /// @notice Add or remove units from a tier's owner-tracked voting-units checkpoint at the current block.
+    /// @param tierId The tier whose owner-tracked 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 {
+        // Ignore zero-unit updates because they do not change this tier's owner-tracked total.
+        if (amount == 0) return;
+
+        // Keep a reference to the tier's owner-tracked voting-units trace.
         Checkpoints.Trace160 storage trace = _tierEligibleUnitsOf[tierId];
+
+        // Calculate the next owner-tracked total by adding or subtracting from the latest checkpointed value.
         uint256 updated = increase ? trace.latest() + amount : trace.latest() - amount;
+
+        // Write the new owner-tracked total at the current block.
         // forge-lint: disable-next-line(unsafe-typecast)
         trace.push({key: uint96(block.number), value: uint160(updated)});
     }

package/src/JB721TiersHook.sol

@@ -244,8 +244,7 @@ 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 if called more than once or if the
-    /// project ID is zero.
+    /// @dev Called by `JB721TiersHookDeployer` after cloning. Reverts if called twice 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.
@@ -461,9 +460,8 @@ contract JB721TiersHook is JBOwnable, ERC2771Context, JB721Hook, IJB721TiersHook
     /// @param symbol The new collection symbol. Send empty to leave unchanged.
     /// @param baseUri The new base URI. Send empty to leave unchanged.
     /// @param contractUri The new contract URI. Send empty to leave unchanged.
-    /// @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 tokenUriResolver The new URI resolver. Pass `IJB721TokenUriResolver(address(this))` to leave it
+    /// unchanged; `address(0)` 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.
     function setMetadata(

package/src/JB721TiersHookProjectDeployer.sol

@@ -114,8 +114,7 @@ contract JB721TiersHookProjectDeployer is
     }
 
     /// @notice Launches rulesets for a project with an attached 721 tiers hook.
-    /// @dev Only a project's owner or an operator with the `LAUNCH_RULESETS & SET_TERMINALS` permission can launch its
-    /// rulesets.
+    /// @dev Only a project's owner or an operator with `LAUNCH_RULESETS & SET_TERMINALS` can launch its rulesets.
     /// @param projectId The ID of the project to launch rulesets for.
     /// @param deployTiersHookConfig Configuration which dictates the behavior of the 721 tiers hook to deploy.
     /// @param launchRulesetsConfig Configuration which dictates the project's new rulesets.
@@ -233,8 +232,7 @@ contract JB721TiersHookProjectDeployer is
     //*********************************************************************//
 
     /// @notice Configure and launch rulesets for a newly created project. Converts `JBPayDataHookRulesetConfig` entries
-    /// into standard `JBRulesetConfig` entries with `useDataHookForPay` forced to `true` and the deployed hook set as
-    /// the data hook.
+    /// into standard `JBRulesetConfig` entries that use the deployed hook as their data hook.
     /// @param projectId The ID of the reserved project.
     /// @param launchProjectConfig Configuration which dictates the behavior of the project to launch.
     /// @param dataHook The data hook to use for the project.

package/src/JB721TiersHookStore.sol

@@ -148,8 +148,7 @@ contract JB721TiersHookStore is IJB721TiersHookStore {
     /// @custom:param hook The 721 contract to get the custom token URI resolver of.
     mapping(address hook => IJB721TokenUriResolver) public override tokenUriResolverOf;
 
-    /// @notice The combined cash-out weight of all of a hook's NFTs, as a running aggregate so cash-out pricing is
-    /// O(1) instead of O(maxTierId).
+    /// @notice The combined cash-out weight of all hook NFTs, tracked so cash-out pricing is O(1).
     /// @dev Maintained incrementally in `recordMint` (+ the tier's full price for the new outstanding NFT plus any
     /// newly-accrued pending reserve) and `recordBurn` (- the tier's full price). It is invariant under everything
     /// else: reserve mints are weight-neutral (a pending reserve becomes an outstanding NFT), removed tiers keep
@@ -610,8 +609,7 @@ contract JB721TiersHookStore is IJB721TiersHookStore {
     /// @param hook The 721 contract to get the tier from.
     /// @param tierId The ID of the tier to get.
     /// @param storedTier The stored tier to get the corresponding tier for.
-    /// @param includeResolvedUri If set to `true`, if the contract has a token URI resolver, its content will be
-    /// resolved and included.
+    /// @param includeResolvedUri If true and the contract has a token URI resolver, resolve and include its content.
     /// @return tier The tier as a `JB721Tier` struct.
     function _getTierFrom(
         address hook,

package/src/abstract/JB721Hook.sol

@@ -135,8 +135,7 @@ abstract contract JB721Hook is ERC721, IJB721Hook {
         cashOutTaxRate = context.cashOutTaxRate;
     }
 
-    /// @notice The data calculated before a payment is recorded in the terminal store. This data is provided to the
-    /// terminal's `pay(...)` transaction.
+    /// @notice The data calculated before a payment is recorded in the terminal store for `pay(...)`.
     /// @dev Sets this contract as the pay hook. Part of `IJBRulesetDataHook`.
     /// @param context The payment context passed to this contract by the `pay(...)` function.
     /// @return weight The new `weight` to use, overriding the ruleset's `weight`.
@@ -164,8 +163,7 @@ abstract contract JB721Hook is ERC721, IJB721Hook {
     // -------------------------- public views --------------------------- //
     //*********************************************************************//
 
-    /// @notice Returns the cumulative cash out weight of the specified token IDs relative to the
-    /// `totalCashOutWeight`.
+    /// @notice Returns the cumulative cash out weight of the specified token IDs relative to `totalCashOutWeight`.
     /// @param tokenIds The NFT token IDs to calculate the cumulative cash out weight of.
     /// @return The cumulative cash out weight of the specified token IDs.
     function cashOutWeightOf(uint256[] memory tokenIds) public view virtual returns (uint256) {
@@ -248,8 +246,7 @@ abstract contract JB721Hook is ERC721, IJB721Hook {
         _didBurn(decodedTokenIds);
     }
 
-    /// @notice Mints one or more NFTs to the `context.beneficiary` upon payment if conditions are met. Part of
-    /// `IJBPayHook`.
+    /// @notice Mints NFTs to `context.beneficiary` upon payment if conditions are met. Part of `IJBPayHook`.
     /// @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 {

package/src/interfaces/IJB721Checkpoints.sol

@@ -3,6 +3,7 @@ pragma solidity ^0.8.0;
 
 import {IJBActiveVotes} from "@bananapus/core-v6/src/interfaces/IJBActiveVotes.sol";
 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.
@@ -10,38 +11,67 @@ import {IJB721TiersHookStore} from "./IJB721TiersHookStore.sol";
 /// Pass this address to JBTokenDistributor as the IVotes token.
 interface IJB721Checkpoints is IERC5805, IJBActiveVotes {
     /// @notice The store that holds tier and voting data for the hook's NFTs.
-    /// @return The store contract.
+    /// @return store The store contract.
     // forge-lint: disable-next-line(mixed-case-function)
-    function STORE() external view returns (IJB721TiersHookStore);
+    function STORE() external view returns (IJB721TiersHookStore store);
+
+    /// @notice The delegated voting units held by an account in a tier at a past block.
+    /// @dev Counts only tier voting units held by `account` while `account` had a nonzero delegate.
+    /// @param account The account to get the delegated tier voting units of.
+    /// @param tierId The tier to get the delegated voting units of.
+    /// @param blockNumber The past block number to look up.
+    /// @return activeVotes The account's delegated tier voting units at `blockNumber`.
+    function getPastAccountTierActiveVotes(
+        address account,
+        uint256 tierId,
+        uint256 blockNumber
+    )
+        external
+        view
+        returns (uint256 activeVotes);
 
-    /// @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.
+    /// @notice The total owner-checkpointed voting units of a tier at a past block.
+    /// @dev Owner-checkpointed voting units are the tier's total owned units, regardless of delegation status.
+    /// @param tierId The tier to get the owner-checkpointed 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);
+    /// @return votingUnits The tier's owner-checkpointed voting units at `blockNumber`.
+    function getPastTierVotingUnits(uint256 tierId, uint256 blockNumber) external view returns (uint256 votingUnits);
+
+    /// @notice The total delegated voting units of a tier at a past block.
+    /// @dev Counts only tier voting units held by accounts with a nonzero delegate.
+    /// @param tierId The tier to get the delegated voting units of.
+    /// @param blockNumber The past block number to look up.
+    /// @return activeVotes The tier's delegated voting units at `blockNumber`.
+    function getPastTotalTierActiveVotes(
+        uint256 tierId,
+        uint256 blockNumber
+    )
+        external
+        view
+        returns (uint256 activeVotes);
+
+    /// @notice The current total delegated voting units of a tier.
+    /// @param tierId The tier to get the current delegated voting units of.
+    /// @return activeVotes The tier's current delegated voting units.
+    function getTotalTierActiveVotes(uint256 tierId) external view returns (uint256 activeVotes);
 
     /// @notice The hook that this module tracks voting power for.
-    /// @return The hook address.
+    /// @return hookAddress The hook address.
     // forge-lint: disable-next-line(mixed-case-function)
-    function hook() external view returns (address);
+    function hook() external view returns (address hookAddress);
 
     /// @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.
+    /// @dev Returns `address(0)` if no ownership checkpoint exists or the query predates the first checkpoint.
     /// @param tokenId The token ID of the NFT to get the historical owner of.
     /// @param blockNumber The block number to look up.
-    /// @return The owner of the token at `blockNumber`, or zero if the token is unenrolled or has no known owner.
-    function ownerOfAt(uint256 tokenId, uint256 blockNumber) external view returns (address);
+    /// @return owner The owner of the token at `blockNumber`, or zero if no owner is proven at that block.
+    function ownerOfAt(uint256 tokenId, uint256 blockNumber) external view returns (address owner);
 
-    /// @notice Delegates voting power and enrolls tokens for distribution eligibility.
-    /// @dev Writes per-token owner checkpoints so `ownerOfAt` can prove ownership at past blocks.
-    /// Only the current token owner can enroll. Tokens without checkpoints are ineligible for snapshot-based
-    /// distribution.
+    /// @notice Delegates voting power and backfills ownership history for listed tokens if needed.
+    /// @dev Mint and transfer hooks normally write owner checkpoints automatically. The token ID list keeps
+    /// pre-upgrade or otherwise uncheckpointed tokens recoverable while preserving the owner-only authorization check.
     /// @param delegatee The address to delegate voting power to. Use your own address for self-delegation.
-    /// @param tokenIds The token IDs to enroll for distribution eligibility.
+    /// @param tokenIds The token IDs whose owner checkpoints should be backfilled if missing.
     function delegate(address delegatee, uint256[] calldata tokenIds) external;
 
     /// @notice Initializes a cloned module with its hook reference.

package/src/interfaces/IJB721TiersHook.sol

@@ -96,8 +96,7 @@ interface IJB721TiersHook is IJB721Hook {
     /// @param caller The address that called the function.
     event SetTokenUriResolver(IJB721TokenUriResolver indexed resolver, address caller);
 
-    /// @notice Emitted when a split payout reverts during distribution. The failed split's funds route to the
-    /// project's balance.
+    /// @notice Emitted when a split payout reverts during distribution, routing funds to the project's balance.
     /// @param projectId The project ID the split belongs to.
     /// @param split The split that reverted.
     /// @param amount The amount that was paid out.
@@ -213,9 +212,8 @@ interface IJB721TiersHook is IJB721Hook {
     /// @param symbol The new collection symbol. Send empty to leave unchanged.
     /// @param baseUri The new base URI. Send empty to leave unchanged.
     /// @param contractUri The new contract URI. Send empty to leave unchanged.
-    /// @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 tokenUriResolver The new URI resolver. Pass `IJB721TokenUriResolver(address(this))` to leave it
+    /// unchanged; `address(0)` 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.
     function setMetadata(

package/src/libraries/JB721TiersHookLib.sol

@@ -73,8 +73,7 @@ library JB721TiersHookLib {
     /// @param caller The address that called the function.
     event SetDiscountPercent(uint256 indexed tierId, uint256 discountPercent, address caller);
 
-    /// @notice Emitted when a split payout reverts during distribution. The failed split's funds route to the
-    /// project's balance.
+    /// @notice Emitted when a split payout reverts during distribution, routing funds to the project's balance.
     /// @param projectId The project ID the split belongs to.
     /// @param split The split that reverted.
     /// @param amount The amount that was paid out.

package/src/structs/JB721TiersRulesetMetadata.sol

@@ -1,8 +1,7 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.0;
 
-/// @notice `JB721TiersHook` options which are packed and stored in the corresponding `JBRulesetMetadata.metadata` on a
-/// per-ruleset basis.
+/// @notice `JB721TiersHook` options packed into each ruleset's `JBRulesetMetadata.metadata`.
 /// @custom:member pauseTransfers A boolean indicating whether NFT transfers are paused during this ruleset.
 /// @custom:member pauseMintPendingReserves A boolean indicating whether pending/outstanding NFT reserves can be minted
 /// during this ruleset.

package/src/structs/JBLaunchProjectConfig.sol

@@ -5,8 +5,7 @@ import {JBTerminalConfig} from "@bananapus/core-v6/src/structs/JBTerminalConfig.
 
 import {JBPayDataHookRulesetConfig} from "./JBPayDataHookRulesetConfig.sol";
 
-/// @custom:member projectUri Metadata URI to associate with the project. This can be updated any time by the owner of
-/// the project.
+/// @custom:member projectUri Metadata URI to associate with the project, updatable by the project owner.
 /// @custom:member rulesetConfigurations The ruleset configurations to queue.
 /// @custom:member terminalConfigurations The terminal configurations to add for the project.
 /// @custom:member memo A memo to pass along to the emitted event.

package/src/structs/JBPayDataHookRulesetConfig.sol

@@ -14,17 +14,14 @@ import {JBPayDataHookRulesetMetadata} from "./JBPayDataHookRulesetMetadata.sol";
 /// a project owner cannot make changes to a ruleset's parameters while it is active – any proposed changes will apply
 /// to the subsequent ruleset. If no changes are proposed, a ruleset rolls over to another one with the same properties
 /// but new `start` timestamp and a decayed `weight`.
-/// @custom:member weight A fixed point number with 18 decimals that contracts can use to base arbitrary calculations
-/// on. For example, payment terminals can use this to determine how many tokens should be minted when a payment is
-/// received.
-/// @custom:member weightCutPercent A percent by how much the `weight` of the subsequent ruleset should be reduced, if
-/// the
-/// project owner hasn't queued the subsequent ruleset with an explicit `weight`. If it's 0, each ruleset will have
-/// equal weight. If the number is 90%, the next ruleset will have a 10% smaller weight. This weight is out of
+/// @custom:member weight A fixed point number with 18 decimals that contracts can use for calculations. For example,
+/// payment terminals can use this to determine how many tokens should be minted when a payment is received.
+/// @custom:member weightCutPercent A percent by how much the `weight` of the subsequent ruleset should be reduced if
+/// the project owner hasn't queued the subsequent ruleset with an explicit `weight`. If it's 0, each ruleset will
+/// have equal weight. If the number is 90%, the next ruleset will have a 10% smaller weight. This weight is out of
 /// `JBConstants.MAX_WEIGHT_CUT_PERCENT`.
-/// @custom:member approvalHook An address of a contract that says whether a proposed ruleset should be accepted or
-/// rejected. It
-/// can be used to create rules around how a project owner can change ruleset parameters over time.
+/// @custom:member approvalHook A contract that says whether a proposed ruleset should be accepted or rejected. It can
+/// create rules around how a project owner changes ruleset parameters over time.
 /// @custom:member metadata Metadata specifying the controller-specific parameters that a ruleset can have. These
 /// properties cannot change until the next ruleset starts.
 /// @custom:member splitGroups An array of splits to use for any number of groups while the ruleset is active.

package/src/structs/JBPayDataHookRulesetMetadata.sol

@@ -13,12 +13,10 @@ pragma solidity ^0.8.0;
 /// permission from the owner should be allowed to mint project tokens on demand during this ruleset.
 /// @custom:member allowSetCustomToken A flag indicating if the project owner can set the project's token to a custom
 /// ERC-20.
-/// @custom:member allowTerminalMigration A flag indicating if migrating terminals should be allowed during this
-/// ruleset.
+/// @custom:member allowTerminalMigration A flag indicating if terminal migration is allowed during this ruleset.
 /// @custom:member allowSetTerminals A flag indicating if a project's terminals can be added or removed.
 /// @custom:member allowSetController A flag indicating if a project's controller can be changed.
-/// @custom:member allowAddAccountingContext A flag indicating if a project can add new accounting contexts for its
-/// terminals to use.
+/// @custom:member allowAddAccountingContext A flag indicating if a project can add accounting contexts to terminals.
 /// @custom:member allowAddPriceFeed A flag indicating if a project can add new price feeds to calculate exchange rates
 /// between its tokens.
 /// @custom:member ownerMustSendPayouts A flag indicating if the owner must manually trigger payout distributions.