@bananapus/721-hook-v6 0.0.74 → 0.0.76

package/README.md

@@ -67,6 +67,12 @@ If a bug affects supply, reserve minting, or tier lookup, it usually lives in th
 - 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.
+- current and historical tier membership is queryable via `hasTiersOfAt(account, tierIds, matchMode, blockNumber)`,
+  using checkpointed per-account tier balances with `Any` and `All` match modes. Empty tier arrays fail closed, and
+  future blocks revert.
+- voting-unit reads and delegation activation use each owner's nonzero held-tier bitmap, not every tier in the catalog.
+  This scans one storage word per 256 tier IDs (at most 256 words at the `uint16` tier cap) plus the owner's held
+  tiers, and updates one bitmap word when an account first enters or fully exits a tier.
 
 ## Where state lives
 

package/package.json

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

package/src/JB721Checkpoints.sol

@@ -7,6 +7,7 @@ import {EIP712} from "@openzeppelin/contracts/utils/cryptography/EIP712.sol";
 import {SafeCast} from "@openzeppelin/contracts/utils/math/SafeCast.sol";
 import {Checkpoints} from "@openzeppelin/contracts/utils/structs/Checkpoints.sol";
 
+import {JB721TierOwnerMatch} from "./enums/JB721TierOwnerMatch.sol";
 import {IJB721Checkpoints} from "./interfaces/IJB721Checkpoints.sol";
 import {IJB721TiersHook} from "./interfaces/IJB721TiersHook.sol";
 import {IJB721TiersHookStore} from "./interfaces/IJB721TiersHookStore.sol";
@@ -62,6 +63,13 @@ contract JB721Checkpoints is Votes, IJB721Checkpoints {
     /// @custom:param tierId The tier to get historical active voting units for.
     mapping(address account => mapping(uint256 tierId => Checkpoints.Trace160)) internal _accountTierActiveVotesOf;
 
+    /// @notice Checkpointed NFT balances per account and tier.
+    /// @dev Maintained by `onTransfer` and owner-checkpoint backfills so tier-membership checks can be queried at a
+    /// block without scanning every token in the tier.
+    /// @custom:param account The account to get historical tier balances for.
+    /// @custom:param tierId The tier to get historical balances for.
+    mapping(address account => mapping(uint256 tierId => Checkpoints.Trace160)) internal _accountTierBalancesOf;
+
     /// @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.
@@ -126,8 +134,16 @@ contract JB721Checkpoints is Votes, IJB721Checkpoints {
             if (_ownerCheckpointsOf[tokenId].length() == 0) {
                 // forge-lint: disable-next-line(unsafe-typecast)
                 _ownerCheckpointsOf[tokenId].push({key: uint96(block.number), value: uint160(msg.sender)});
+
+                // Reuse the token's encoded tier ID for both account-balance and tier-supply traces.
+                uint256 tierId = STORE.tierIdOfToken(tokenId);
+
+                // Add this backfilled token to the caller's checkpointed tier balance.
+                _adjustAccountTierBalance({account: msg.sender, tierId: tierId, increase: true});
+
+                // Add this backfilled token's units to the tier's owner-tracked total.
                 _updateTierEligibleUnits({
-                    tierId: STORE.tierIdOfToken(tokenId),
+                    tierId: tierId,
                     amount: STORE.tierVotingUnitsOfTokenId({hook: hook, tokenId: tokenId}),
                     increase: true
                 });
@@ -144,7 +160,10 @@ contract JB721Checkpoints is Votes, IJB721Checkpoints {
     /// @param hookAddress The hook this module serves.
     function initialize(address hookAddress) external override {
         if (hook != address(0)) revert JB721Checkpoints_AlreadyInitialized({hook: hook});
-        // `hook` cannot be zero when called through the deployer because `msg.sender` must equal `hook`.
+        // No caller check is needed (and there is none): `JB721CheckpointsDeployer.deploy` creates this clone with
+        // the hook as the CREATE2 salt and calls `initialize(hook)` atomically in the same call, so a clone can only
+        // ever be bound to its salt-designated hook and there is no front-run window between cloning and init. The
+        // implementation itself is locked against direct use by the `address(1)` sentinel set in its constructor.
         hook = hookAddress;
     }
 
@@ -156,6 +175,9 @@ 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});
 
+        // Self-transfers leave ownership, voting units, and tier-balance traces unchanged.
+        if (from == to) return;
+
         // Look up this token's tier ID and voting units once; both the owner and active traces need them.
         uint256 tierId = STORE.tierIdOfToken(tokenId);
 
@@ -176,15 +198,22 @@ contract JB721Checkpoints is Votes, IJB721Checkpoints {
 
         if (from == address(0) && to != address(0)) {
             // Mint: add the token's tier units to the owner-tracked tier supply.
+            _adjustAccountTierBalance({account: to, tierId: tierId, increase: true});
             _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) {
+                _adjustAccountTierBalance({account: from, tierId: tierId, increase: false});
                 _updateTierEligibleUnits({tierId: tierId, amount: votingUnits, increase: false});
             }
         } else if (!wasEligible) {
             // First transfer of a pre-upgrade uncheckpointed token makes its ownership history trackable.
+            _adjustAccountTierBalance({account: to, tierId: tierId, increase: true});
             _updateTierEligibleUnits({tierId: tierId, amount: votingUnits, increase: true});
+        } else {
+            // Transfer: move one tier balance unit between checkpointed accounts.
+            _adjustAccountTierBalance({account: from, tierId: tierId, increase: false});
+            _adjustAccountTierBalance({account: to, tierId: tierId, increase: true});
         }
 
         // The tier active total decreases if units leave an account that already has a nonzero delegate.
@@ -295,14 +324,66 @@ contract JB721Checkpoints is Votes, IJB721Checkpoints {
         activeVotes = _tierActiveSupplyCheckpointsOf[tierId].latest();
     }
 
-    /// @notice The owner of an NFT at a past block.
+    /// @notice Whether an owner held any or all of the provided tier IDs at a block.
+    /// @dev Empty arrays return `false`. `blockNumber` may be the current block, but not a future block.
+    /// @param account The account to check.
+    /// @param tierIds The tier IDs to check.
+    /// @param matchMode Whether to require any or all tier IDs to be held.
+    /// @param blockNumber The block number to look up.
+    /// @return hasTiers Whether the owner satisfies the requested tier match at `blockNumber`.
+    function hasTiersOfAt(
+        address account,
+        uint256[] calldata tierIds,
+        JB721TierOwnerMatch matchMode,
+        uint256 blockNumber
+    )
+        external
+        view
+        override
+        returns (bool hasTiers)
+    {
+        // Empty tier requirements fail closed so default-decoded calls cannot grant membership.
+        if (tierIds.length == 0) return false;
+
+        // Convert once so every tier lookup uses the same checkpoint key.
+        uint96 blockNumber96 = _validateCurrentOrPastTimepoint(blockNumber);
+
+        if (matchMode == JB721TierOwnerMatch.Any) {
+            // In `Any` mode, one nonzero tier balance is enough to satisfy the query.
+            for (uint256 i; i < tierIds.length;) {
+                // A nonzero checkpointed balance means the account held this tier at the requested block.
+                if (_accountTierBalancesOf[account][tierIds[i]].upperLookupRecent(blockNumber96) != 0) return true;
+
+                unchecked {
+                    ++i;
+                }
+            }
+
+            // None of the queried tiers had a nonzero balance for the account at the requested block.
+            return false;
+        }
+
+        // In `All` mode, every queried tier must have a nonzero balance.
+        for (uint256 i; i < tierIds.length;) {
+            // Missing any queried tier is enough to fail the all-tiers match.
+            if (_accountTierBalancesOf[account][tierIds[i]].upperLookupRecent(blockNumber96) == 0) return false;
+
+            unchecked {
+                ++i;
+            }
+        }
+
+        // Every queried tier matched.
+        return true;
+    }
+
+    /// @notice The owner of an NFT at a current or past block.
     /// @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.
+    /// @param blockNumber The current or past block number to look up.
     /// @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);
+        uint96 blockNumber96 = _validateCurrentOrPastTimepoint(blockNumber);
 
         Checkpoints.Trace160 storage checkpoints = _ownerCheckpointsOf[tokenId];
         uint256 checkpointCount = checkpoints.length();
@@ -398,18 +479,15 @@ contract JB721Checkpoints is Votes, IJB721Checkpoints {
     /// @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;
+        _pushTraceDelta({trace: _accountTierActiveVotesOf[account][tierId], amount: amount, increase: increase});
+    }
 
-        // 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 one NFT from an account's tier-balance checkpoint at the current block.
+    /// @param account The account whose tier-balance trace should be updated.
+    /// @param tierId The tier whose balance should be updated.
+    /// @param increase Whether to add one NFT; if false, one NFT is removed.
+    function _adjustAccountTierBalance(address account, uint256 tierId, bool increase) private {
+        _pushTraceDelta({trace: _accountTierBalancesOf[account][tierId], amount: 1, increase: increase});
     }
 
     /// @notice Add or remove units from a tier's active-voting-units checkpoint at the current block.
@@ -417,18 +495,7 @@ contract JB721Checkpoints is Votes, IJB721Checkpoints {
     /// @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)});
+        _pushTraceDelta({trace: _tierActiveSupplyCheckpointsOf[tierId], amount: amount, increase: increase});
     }
 
     /// @notice Apply an account delegation change to every tier-level active total the account contributes to.
@@ -437,25 +504,28 @@ contract JB721Checkpoints is Votes, IJB721Checkpoints {
     /// @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);
+        // Read the account's held-tier IDs and voting units once so empty tiers are never visited.
+        (uint256[] memory tierIds, uint256[] memory tierVotingUnits) =
+            STORE.heldTierVotingUnitsOf({hook: hook, account: account});
 
-        // 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});
+        // Walk only tiers the account currently holds.
+        for (uint256 i; i < tierIds.length;) {
+            // Get a reference to the tier ID being iterated on.
+            uint256 tierId = tierIds[i];
+
+            // Keep a reference to this account's voting units for the tier.
+            uint256 votingUnits = tierVotingUnits[i];
 
             // Only write checkpoints for tiers whose active totals actually change.
-            if (tierVotingUnits != 0) {
-                _adjustTotalTierActiveVotes({tierId: tierId, amount: tierVotingUnits, increase: increase});
+            if (votingUnits != 0) {
+                _adjustTotalTierActiveVotes({tierId: tierId, amount: votingUnits, increase: increase});
                 _adjustAccountTierActiveVotes({
-                    account: account, tierId: tierId, amount: tierVotingUnits, increase: increase
+                    account: account, tierId: tierId, amount: votingUnits, increase: increase
                 });
             }
 
             unchecked {
-                // The loop condition proves tierId is nonzero, so the decrement cannot underflow.
-                --tierId;
+                ++i;
             }
         }
     }
@@ -482,17 +552,30 @@ contract JB721Checkpoints is Votes, IJB721Checkpoints {
     /// @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;
+        _pushTraceDelta({trace: _tierEligibleUnitsOf[tierId], amount: amount, increase: increase});
+    }
 
-        // Keep a reference to the tier's owner-tracked voting-units trace.
-        Checkpoints.Trace160 storage trace = _tierEligibleUnitsOf[tierId];
+    /// @notice Add or remove an amount from a `Trace160` checkpoint at the current block.
+    /// @param trace The checkpoint trace to update.
+    /// @param amount The amount to add or remove.
+    /// @param increase Whether to add `amount`; if false, `amount` is removed.
+    function _pushTraceDelta(Checkpoints.Trace160 storage trace, uint256 amount, bool increase) private {
+        // Ignore zero-unit updates because they do not change the checkpointed total.
+        if (amount == 0) return;
 
-        // Calculate the next owner-tracked total by adding or subtracting from the latest checkpointed value.
+        // Calculate the next trace 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)});
+        // Write the new trace total at the current block.
+        trace.push({key: uint96(block.number), value: SafeCast.toUint160(updated)});
+    }
+
+    /// @notice Validate a timepoint that may be current or past, but not future.
+    /// @param timepoint The block number to validate.
+    /// @return The timepoint as a uint96 checkpoint key.
+    function _validateCurrentOrPastTimepoint(uint256 timepoint) private view returns (uint96) {
+        uint48 currentTimepoint = clock();
+        if (timepoint > currentTimepoint) revert ERC5805FutureLookup(timepoint, currentTimepoint);
+        return SafeCast.toUint96(timepoint);
     }
 }

package/src/JB721TiersHookStore.sol

@@ -1,8 +1,9 @@
 // SPDX-License-Identifier: MIT
 pragma solidity 0.8.28;
 
-import {mulDiv} from "@prb/math/src/Common.sol";
 import {JBConstants} from "@bananapus/core-v6/src/libraries/JBConstants.sol";
+import {mulDiv} from "@prb/math/src/Common.sol";
+import {LibBit} from "solady/src/utils/LibBit.sol";
 
 import {IJB721TiersHookStore} from "./interfaces/IJB721TiersHookStore.sol";
 import {IJB721TokenUriResolver} from "./interfaces/IJB721TokenUriResolver.sol";
@@ -166,6 +167,15 @@ contract JB721TiersHookStore is IJB721TiersHookStore {
     /// @custom:returns The flags.
     mapping(address hook => JB721TiersHookFlags) internal _flagsOf;
 
+    /// @notice Bitmap words whose set bits indicate tier IDs with nonzero balances for the provided owner.
+    /// @dev Maintained in `recordTransferForTier`, so voting-unit reads and delegation updates walk set bits instead
+    /// of every tier ever added to the hook. Each word tracks 256 tier IDs.
+    /// @custom:param hook The 721 contract to get held tier IDs from.
+    /// @custom:param owner The address to get held tier IDs for.
+    /// @custom:param depth The bitmap word depth to read. Each depth stores 256 tier IDs.
+    mapping(address hook => mapping(address owner => mapping(uint256 depth => uint256 word))) internal
+        _heldTiersBitmapWordOf;
+
     /// @notice Return the ID of the last sorted tier from the provided 721 contract.
     /// @dev If not set, it is assumed the `maxTierIdOf` is the last sorted tier ID.
     /// @custom:param hook The 721 contract to get the last sorted tier ID from.
@@ -232,6 +242,72 @@ contract JB721TiersHookStore is IJB721TiersHookStore {
         return _flagsOf[hook];
     }
 
+    /// @notice The tier IDs whose balances are nonzero for the provided owner.
+    /// @param hook The 721 hook contract to get held tier IDs from.
+    /// @param owner The address to get held tier IDs for.
+    /// @return tierIds The tier IDs with a nonzero balance for the owner.
+    function heldTierIdsOf(
+        address hook,
+        address owner
+    )
+        external
+        view
+        virtual
+        override
+        returns (uint256[] memory tierIds)
+    {
+        return _heldTierIdsOf({hook: hook, owner: owner});
+    }
+
+    /// @notice The tier IDs and voting units whose balances are nonzero for the provided account.
+    /// @param hook The 721 hook contract to get held tier IDs from.
+    /// @param account The address to get held tier IDs and voting units for.
+    /// @return tierIds The tier IDs with a nonzero balance for the account.
+    /// @return units The account's voting units for each returned tier ID.
+    function heldTierVotingUnitsOf(
+        address hook,
+        address account
+    )
+        external
+        view
+        virtual
+        override
+        returns (uint256[] memory tierIds, uint256[] memory units)
+    {
+        // Allocate both arrays to the exact number of held tier IDs.
+        tierIds = new uint256[](_numberOfHeldTiersOf({hook: hook, owner: account}));
+        units = new uint256[](tierIds.length);
+
+        // Fill both arrays in ascending tier ID order.
+        uint256 index;
+        uint256 maxDepth = maxTierIdOf[hook] >> 8;
+        for (uint256 depth; depth <= maxDepth;) {
+            // Keep a local copy so consumed bits do not mutate storage.
+            uint256 heldTiersBitmapWord = _heldTiersBitmapWordOf[hook][account][depth];
+
+            // Resolve each set bit to its tier ID and voting units.
+            while (heldTiersBitmapWord != 0) {
+                // Store the tier ID represented by the lowest set bit.
+                uint256 tierId = (depth << 8) + LibBit.ffs(heldTiersBitmapWord);
+                tierIds[index] = tierId;
+
+                // Store the account's voting units for the tier at the same index.
+                units[index] = _votingUnitsForHeldTier({hook: hook, account: account, tierId: tierId});
+
+                unchecked {
+                    ++index;
+                }
+
+                // Clear the consumed bit from the local word.
+                heldTiersBitmapWord &= heldTiersBitmapWord - 1;
+            }
+
+            unchecked {
+                ++depth;
+            }
+        }
+    }
+
     /// @notice Check whether a tier has been removed. Removed tiers can no longer be minted from, but existing NFTs
     /// from that tier remain valid and can still be cashed out.
     /// @param hook The 721 hook contract the tier belongs to.
@@ -441,19 +517,7 @@ contract JB721TiersHookStore is IJB721TiersHookStore {
         override
         returns (uint256)
     {
-        // Get a reference to the account's balance in this tier.
-        uint256 balance = tierBalanceOf[hook][account][tierId];
-
-        if (balance == 0) return 0;
-
-        // Keep a reference to the stored tier.
-        JBStored721Tier memory storedTier = _storedTierOf[hook][tierId];
-
-        // Check if voting units should be used. Price will be used otherwise.
-        (,, bool useVotingUnits,,,) = _unpackBools(storedTier.packedBools);
-
-        // Return the address' voting units within the tier.
-        return balance * (useVotingUnits ? _tierVotingUnitsOf[hook][tierId] : storedTier.price);
+        return _votingUnitsForHeldTier({hook: hook, account: account, tierId: tierId});
     }
 
     /// @notice The total number of NFTs currently in circulation for a hook (minted minus burned, across all tiers).
@@ -486,34 +550,27 @@ contract JB721TiersHookStore is IJB721TiersHookStore {
     /// @param account The address to get the voting unit total of.
     /// @return units The total voting units the address holds across all tiers.
     function votingUnitsOf(address hook, address account) external view virtual override returns (uint256 units) {
-        // Keep a reference to the greatest tier ID.
-        uint256 maxTierId = maxTierIdOf[hook];
-
-        // Loop through all tiers.
-        for (uint256 i = maxTierId; i != 0;) {
-            // Get a reference to the account's balance in this tier.
-            uint256 balance = tierBalanceOf[hook][account][i];
+        // Keep a reference to the last bitmap word which can contain a valid tier ID.
+        uint256 maxDepth = maxTierIdOf[hook] >> 8;
+
+        // Loop only through 256-tier bitmap words that can contain known tiers.
+        for (uint256 depth; depth <= maxDepth;) {
+            // Keep a local copy so consumed bits do not mutate storage.
+            uint256 heldTiersBitmapWord = _heldTiersBitmapWordOf[hook][account][depth];
+
+            // Walk only set bits, so empty tiers in the word are skipped.
+            while (heldTiersBitmapWord != 0) {
+                // Add the voting units represented by the lowest set bit.
+                units += _votingUnitsForHeldTier({
+                    hook: hook, account: account, tierId: (depth << 8) + LibBit.ffs(heldTiersBitmapWord)
+                });
 
-            // If the account has no balance, return.
-            if (balance == 0) {
-                unchecked {
-                    --i;
-                }
-                continue;
+                // Clear the consumed bit from the local word.
+                heldTiersBitmapWord &= heldTiersBitmapWord - 1;
             }
 
-            // Get the tier.
-            JBStored721Tier memory storedTier = _storedTierOf[hook][i];
-
-            // Parse the flags.
-            (,, bool useVotingUnits,,,) = _unpackBools(storedTier.packedBools);
-
-            // Add the voting units for the address' balance in this tier.
-            // Use custom voting units if set. Otherwise, use the tier's price.
-            units += balance * (useVotingUnits ? _tierVotingUnitsOf[hook][i] : storedTier.price);
-
             unchecked {
-                --i;
+                ++depth;
             }
         }
     }
@@ -656,6 +713,58 @@ contract JB721TiersHookStore is IJB721TiersHookStore {
         });
     }
 
+    /// @notice The tier IDs whose balances are nonzero for the provided owner.
+    /// @param hook The 721 hook contract to get held tier IDs from.
+    /// @param owner The address to get held tier IDs for.
+    /// @return tierIds The tier IDs with a nonzero balance for the owner.
+    function _heldTierIdsOf(address hook, address owner) internal view returns (uint256[] memory tierIds) {
+        // Allocate the exact number of held tier IDs.
+        tierIds = new uint256[](_numberOfHeldTiersOf({hook: hook, owner: owner}));
+
+        // Fill the returned array in ascending tier ID order.
+        uint256 index;
+        uint256 maxDepth = maxTierIdOf[hook] >> 8;
+        for (uint256 depth; depth <= maxDepth;) {
+            // Keep a local copy so consumed bits do not mutate storage.
+            uint256 heldTiersBitmapWord = _heldTiersBitmapWordOf[hook][owner][depth];
+
+            // Resolve each set bit to its tier ID.
+            while (heldTiersBitmapWord != 0) {
+                // Store the tier ID represented by the lowest set bit.
+                tierIds[index] = (depth << 8) + LibBit.ffs(heldTiersBitmapWord);
+
+                unchecked {
+                    ++index;
+                }
+
+                // Clear the consumed bit from the local word.
+                heldTiersBitmapWord &= heldTiersBitmapWord - 1;
+            }
+
+            unchecked {
+                ++depth;
+            }
+        }
+    }
+
+    /// @notice The number of tier IDs whose balances are nonzero for the provided owner.
+    /// @param hook The 721 hook contract to count held tier IDs from.
+    /// @param owner The address to count held tier IDs for.
+    /// @return numberOfHeldTiers The number of tier IDs with a nonzero balance for the owner.
+    function _numberOfHeldTiersOf(address hook, address owner) internal view returns (uint256 numberOfHeldTiers) {
+        // Keep a reference to the last bitmap word which can contain a valid tier ID.
+        uint256 maxDepth = maxTierIdOf[hook] >> 8;
+
+        for (uint256 depth; depth <= maxDepth;) {
+            // Count only set bits, because each set bit represents one held tier ID.
+            numberOfHeldTiers += LibBit.popCount(_heldTiersBitmapWordOf[hook][owner][depth]);
+
+            unchecked {
+                ++depth;
+            }
+        }
+    }
+
     /// @notice Check whether a tier has been removed while refreshing the relevant bitmap word if needed.
     /// @param hook The 721 contract to check for removals on.
     /// @param tierId The ID of the tier to check the removal status of.
@@ -763,6 +872,27 @@ contract JB721TiersHookStore is IJB721TiersHookStore {
         }
     }
 
+    /// @notice Get an address's voting units within one held tier.
+    /// @param hook The 721 hook contract that the tier belongs to.
+    /// @param account The address to get voting units for.
+    /// @param tierId The ID of the tier.
+    /// @return units The account's total voting units within the tier.
+    function _votingUnitsForHeldTier(address hook, address account, uint256 tierId) internal view returns (uint256) {
+        // Get a reference to the account's balance in this tier.
+        uint256 balance = tierBalanceOf[hook][account][tierId];
+
+        if (balance == 0) return 0;
+
+        // Keep a reference to the stored tier.
+        JBStored721Tier memory storedTier = _storedTierOf[hook][tierId];
+
+        // Check if voting units should be used. Price will be used otherwise.
+        (,, bool useVotingUnits,,,) = _unpackBools(storedTier.packedBools);
+
+        // Return the address' voting units within the tier.
+        return balance * (useVotingUnits ? _tierVotingUnitsOf[hook][tierId] : storedTier.price);
+    }
+
     /// @notice Pack six tier-level boolean flags into a single uint8 for compact storage in `JBStored721Tier`.
     /// @dev Bit layout: 0=allowOwnerMint, 1=transfersPausable, 2=useVotingUnits, 3=cantBeRemoved,
     /// 4=cantIncreaseDiscountPercent, 5=cantBuyWithCredits.
@@ -1458,20 +1588,56 @@ contract JB721TiersHookStore is IJB721TiersHookStore {
     /// @param from The address to transfer the 721 from.
     /// @param to The address to transfer the 721 to.
     function recordTransferForTier(uint256 tierId, address from, address to) external override {
+        // Self-transfers leave the per-tier balance, aggregate balance, and held-tier bitmap unchanged.
+        if (from == to) return;
+
         // If this is not a mint,
         if (from != address(0)) {
-            // then subtract the tier balance from the sender, and the running per-owner balance read by `balanceOf`.
-            --tierBalanceOf[msg.sender][from][tierId];
+            // then subtract the tier balance from the sender.
+            uint256 fromTierBalance = --tierBalanceOf[msg.sender][from][tierId];
+
+            // Remove the tier from the sender's held bitmap if this transfer consumed their last NFT in the tier.
+            if (fromTierBalance == 0) _removeHeldTier({hook: msg.sender, owner: from, tierId: tierId});
+
+            // Keep the running per-owner balance read by `balanceOf` in sync.
             --balanceOf[msg.sender][from];
         }
 
         // If this is not a burn,
         if (to != address(0)) {
+            // Keep a reference to the receiver's current tier balance before mutating it.
+            uint256 toTierBalance = tierBalanceOf[msg.sender][to][tierId];
+
+            // Add the tier to the receiver's held bitmap before their first NFT in the tier is recorded.
+            if (toTierBalance == 0) _addHeldTier({hook: msg.sender, owner: to, tierId: tierId});
+
             unchecked {
                 // then increase the tier balance for the receiver, and the running per-owner balance.
-                ++tierBalanceOf[msg.sender][to][tierId];
+                tierBalanceOf[msg.sender][to][tierId] = toTierBalance + 1;
                 ++balanceOf[msg.sender][to];
             }
         }
     }
+
+    //*********************************************************************//
+    // ----------------------- internal helpers -------------------------- //
+    //*********************************************************************//
+
+    /// @notice Add a tier to an owner's held-tier bitmap.
+    /// @param hook The 721 hook contract the tier belongs to.
+    /// @param owner The owner whose held-tier bitmap is being updated.
+    /// @param tierId The tier ID to add.
+    function _addHeldTier(address hook, address owner, uint256 tierId) internal {
+        // Set the bit representing this tier ID.
+        _heldTiersBitmapWordOf[hook][owner].setId(tierId);
+    }
+
+    /// @notice Remove a tier from an owner's held-tier bitmap.
+    /// @param hook The 721 hook contract the tier belongs to.
+    /// @param owner The owner whose held-tier bitmap is being updated.
+    /// @param tierId The tier ID to remove.
+    function _removeHeldTier(address hook, address owner, uint256 tierId) internal {
+        // Clear the bit representing this tier ID.
+        _heldTiersBitmapWordOf[hook][owner].clearId(tierId);
+    }
 }

package/src/abstract/JB721Hook.sol

@@ -70,7 +70,7 @@ abstract contract JB721Hook is ERC721, IJB721Hook {
     /// @param directory A directory of terminals and controllers for projects.
     constructor(IJBDirectory directory) {
         DIRECTORY = directory;
-        // Store the implementation address. Clones use their own address when they initialize.
+        // Store the implementation address shared by clones, since immutables are baked into the reference bytecode.
         METADATA_ID_TARGET = address(this);
     }
 

package/src/enums/JB721TierOwnerMatch.sol

@@ -0,0 +1,8 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+/// @notice How to match tier ownership for an account against a provided tier ID list.
+enum JB721TierOwnerMatch {
+    Any,
+    All
+}

package/src/interfaces/IJB721Checkpoints.sol

@@ -4,6 +4,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 {JB721TierOwnerMatch} from "../enums/JB721TierOwnerMatch.sol";
 import {IJB721TiersHookStore} from "./IJB721TiersHookStore.sol";
 
 /// @notice A checkpoint module that provides IVotes-compatible checkpointed voting power for a JB721TiersHook.
@@ -55,15 +56,32 @@ interface IJB721Checkpoints is IERC5805, IJBActiveVotes {
     /// @return activeVotes The tier's current delegated voting units.
     function getTotalTierActiveVotes(uint256 tierId) external view returns (uint256 activeVotes);
 
+    /// @notice Whether an owner held any or all of the provided tier IDs at a block.
+    /// @dev Empty arrays return `false`. `blockNumber` may be the current block, but not a future block.
+    /// @param account The account to check.
+    /// @param tierIds The tier IDs to check.
+    /// @param matchMode Whether to require any or all tier IDs to be held.
+    /// @param blockNumber The block number to look up.
+    /// @return hasTiers Whether the owner satisfies the requested tier match at `blockNumber`.
+    function hasTiersOfAt(
+        address account,
+        uint256[] calldata tierIds,
+        JB721TierOwnerMatch matchMode,
+        uint256 blockNumber
+    )
+        external
+        view
+        returns (bool hasTiers);
+
     /// @notice The hook that this module tracks voting power for.
     /// @return hookAddress The hook address.
     // forge-lint: disable-next-line(mixed-case-function)
     function hook() external view returns (address hookAddress);
 
-    /// @notice The owner of an NFT at a past block.
+    /// @notice The owner of an NFT at a current or past block.
     /// @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.
+    /// @param blockNumber The current or past block number to look up.
     /// @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);
 

package/src/interfaces/IJB721TiersHookStore.sol

@@ -56,6 +56,25 @@ interface IJB721TiersHookStore {
     /// @return The flags.
     function flagsOf(address hook) external view returns (JB721TiersHookFlags memory);
 
+    /// @notice The tier IDs whose balances are nonzero for the provided owner.
+    /// @param hook The 721 contract to get held tier IDs from.
+    /// @param owner The address to get held tier IDs for.
+    /// @return tierIds The tier IDs with a nonzero balance for the owner.
+    function heldTierIdsOf(address hook, address owner) external view returns (uint256[] memory tierIds);
+
+    /// @notice The tier IDs and voting units whose balances are nonzero for the provided account.
+    /// @param hook The 721 contract to get held tier IDs from.
+    /// @param account The address to get held tier IDs and voting units for.
+    /// @return tierIds The tier IDs with a nonzero balance for the account.
+    /// @return units The account's voting units for each returned tier ID.
+    function heldTierVotingUnitsOf(
+        address hook,
+        address account
+    )
+        external
+        view
+        returns (uint256[] memory tierIds, uint256[] memory units);
+
     /// @notice Check if the provided tier has been removed from the provided 721 contract.
     /// @param hook The 721 contract the tier belongs to.
     /// @param tierId The ID of the tier to check the removal status of.

package/src/libraries/JBBitmap.sol

@@ -43,12 +43,33 @@ library JBBitmap {
         return _retrieveDepth(index) != self.currentDepth;
     }
 
+    /// @notice Clear the bit at the given index.
+    /// @param self The bitmap to clear the bit from.
+    /// @param index The index of the bit to clear.
+    function clearId(mapping(uint256 => uint256) storage self, uint256 index) internal {
+        self[_retrieveDepth(index)] &= ~_retrieveBitMask(index);
+    }
+
     /// @notice Set the bit at the given index to true, indicating that the corresponding tier has been removed.
     /// @dev This is a one-way operation.
     function removeTier(mapping(uint256 => uint256) storage self, uint256 index) internal {
-        uint256 depth = _retrieveDepth(index);
+        setId({self: self, index: index});
+    }
+
+    /// @notice Set the bit at the given index.
+    /// @param self The bitmap to set the bit in.
+    /// @param index The index of the bit to set.
+    function setId(mapping(uint256 => uint256) storage self, uint256 index) internal {
+        self[_retrieveDepth(index)] |= _retrieveBitMask(index);
+    }
+
+    /// @notice Return the bit mask of a given index within its bitmap row.
+    /// @param index The index to get a bit mask for.
+    /// @return mask The bit mask for `index`.
+    function _retrieveBitMask(uint256 index) internal pure returns (uint256 mask) {
+        // The modulo keeps the bit offset inside one 256-bit bitmap word.
         // forge-lint: disable-next-line(incorrect-shift)
-        self[depth] |= uint256(1 << (index % 256));
+        return 1 << (index % 256);
     }
 
     /// @notice Return the line number (depth) of a given index within the bitmap matrix.

package/test/utils/ForTest_JB721TiersHook.sol

@@ -232,9 +232,20 @@ contract ForTest_JB721TiersHookStore is JB721TiersHookStore, IJB721TiersHookStor
 
     // forge-lint: disable-next-line(mixed-case-function)
     function ForTest_setBalanceOf(address hook, address holder, uint256 tier, uint256 balance) public override {
+        // Keep a reference to the manufactured balance before the override.
+        uint256 currentBalance = tierBalanceOf[address(hook)][holder][tier];
+
         // Keep the O(1) `balanceOf` aggregate in sync with the manufactured per-tier balance.
-        balanceOf[address(hook)][holder] =
-            balanceOf[address(hook)][holder] - tierBalanceOf[address(hook)][holder][tier] + balance;
+        balanceOf[address(hook)][holder] = balanceOf[address(hook)][holder] - currentBalance + balance;
+
+        // Keep the held-tier bitmap in sync with zero/nonzero balance transitions.
+        if (currentBalance == 0 && balance != 0) {
+            _addHeldTier({hook: address(hook), owner: holder, tierId: tier});
+        } else if (currentBalance != 0 && balance == 0) {
+            _removeHeldTier({hook: address(hook), owner: holder, tierId: tier});
+        }
+
+        // Store the manufactured per-tier balance.
         tierBalanceOf[address(hook)][holder][tier] = balance;
     }