@bananapus/distributor-v6 0.0.33 → 0.0.35

package/src/JB721Distributor.sol

@@ -41,6 +41,10 @@ contract JB721Distributor is JBDistributor, IJB721Distributor {
     /// @notice Thrown when native ETH does not match the split hook context amount.
     error JB721Distributor_NativeAmountMismatch(uint256 msgValue, uint256 contextAmount);
 
+    /// @notice Thrown when a tier-scoped call's tier IDs are not strictly increasing (so a canonical group ID
+    /// cannot be derived).
+    error JB721Distributor_TierIdsNotIncreasing(uint256 previousTierId, uint256 tierId);
+
     /// @notice Thrown when claim batch NFT token IDs are not strictly increasing.
     error JB721Distributor_TokenIdsNotIncreasing(uint256 previousTokenId, uint256 tokenId);
 
@@ -63,9 +67,12 @@ contract JB721Distributor is JBDistributor, IJB721Distributor {
 
     /// @notice The next reward round an NFT token ID has not yet claimed.
     /// @custom:param hook The 721 hook whose NFTs are claiming.
+    /// @custom:param groupId The reward group (0 = all tiers).
     /// @custom:param tokenId The NFT token ID.
     /// @custom:param token The reward token being claimed.
-    mapping(address hook => mapping(uint256 tokenId => mapping(IERC20 token => uint256))) public nextClaimRoundOf;
+    mapping(
+        address hook => mapping(uint256 groupId => mapping(uint256 tokenId => mapping(IERC20 token => uint256)))
+    ) public nextClaimRoundOf;
 
     //*********************************************************************//
     // -------------------- internal stored properties ------------------- //
@@ -80,6 +87,12 @@ contract JB721Distributor is JBDistributor, IJB721Distributor {
         address hook => mapping(IERC20 token => mapping(uint256 rewardRound => mapping(address owner => uint256)))
     ) internal _consumedVotesOf;
 
+    /// @notice The tier set that defines a reward group, recorded the first time the group is funded.
+    /// @dev Empty for the default group (0 = all tiers). Read by the stake math to scope the tier-set denominator.
+    /// @custom:param hook The hook the group belongs to.
+    /// @custom:param groupId The reward group.
+    mapping(address hook => mapping(uint256 groupId => uint256[])) internal _tierIdsOfGroup;
+
     //*********************************************************************//
     // -------------------------- constructor ---------------------------- //
     //*********************************************************************//
@@ -139,8 +152,8 @@ contract JB721Distributor is JBDistributor, IJB721Distributor {
             }
 
             if (msg.value != 0) {
-                // Assign native split proceeds to the current reward round for this 721 hook.
-                _recordRewardFunding({hook: hook, token: IERC20(context.token), amount: msg.value});
+                // Split-funded pots go to the all-tiers group (0); a split cannot carry a tier set.
+                _recordRewardFunding({hook: hook, groupId: 0, token: IERC20(context.token), amount: msg.value});
             }
         } else {
             // Validate that native ETH is not cross-booked under an ERC-20 token.
@@ -157,61 +170,209 @@ contract JB721Distributor is JBDistributor, IJB721Distributor {
             uint256 delta =
                 _acceptErc20FundsFrom({token: IERC20(context.token), from: msg.sender, amount: context.amount});
 
-            // Assign only the amount actually received to this round's reward pot.
-            _recordRewardFunding({hook: hook, token: IERC20(context.token), amount: delta});
+            // Assign only the amount actually received to this round's reward pot (all-tiers group, 0).
+            _recordRewardFunding({hook: hook, groupId: 0, token: IERC20(context.token), amount: delta});
         }
     }
 
-    /// @notice Snapshot this NFT's past reward rounds and start vesting them now.
-    /// @dev Current-round funding is excluded. It becomes claimable once a later round starts.
-    /// @param hook The 721 hook whose NFTs are vesting.
-    /// @param tokenIds The NFT token IDs to claim for.
+    // The group-0 (all-tiers) `beginVesting` and `collectVestedRewards` are provided by `JBDistributor`. Both
+    // distributors share the exact same flow (authorize -> materialize past rounds via `_claimPastRewards` ->
+    // optionally release unlocked), so the round-claim logic lives once in the base and dispatches to this contract's
+    // `_claimPastRewards` / `_requireCanClaimTokenIds` overrides below. The tier-scoped overloads below derive a
+    // canonical group ID from the tier set and call the same base helpers.
+
+    /// @notice Begin vesting all unclaimed past reward rounds for the specified NFT token IDs in a tier-scoped group.
+    /// @param hook The 721 hook whose NFT owners are vesting.
+    /// @param tierIds The strictly-increasing tier set defining the group.
+    /// @param tokenIds The NFT token IDs to claim rewards for.
     /// @param tokens The reward tokens to begin vesting.
     function beginVesting(
         address hook,
+        uint256[] calldata tierIds,
         uint256[] calldata tokenIds,
         IERC20[] calldata tokens
     )
         external
-        override(JBDistributor, IJBDistributor)
+        override
     {
-        // Do not let reward-token callbacks mutate claim accounting during an inbound transfer.
-        _requireNotAcceptingToken();
-        if (tokenIds.length == 0) revert JBDistributor_EmptyTokenIds({tokenIdCount: tokenIds.length});
+        _beginVesting({hook: hook, groupId: _groupIdFor(tierIds), tokenIds: tokenIds, tokens: tokens});
+    }
 
-        // Only the current NFT owner can start vesting for each token ID.
-        _requireCanClaimTokenIds({hook: hook, tokenIds: tokenIds});
+    /// @notice Fund a tier-scoped reward group: only holders of the given tiers can claim this pot.
+    /// @dev For native ETH, send `msg.value` and pass `IERC20(JBConstants.NATIVE_TOKEN)` as the token. Uses balance
+    /// delta to handle fee-on-transfer tokens correctly. The tier set is recorded on the group's first funding.
+    /// @param hook The 721 hook to fund (determines which staker pool receives the tokens).
+    /// @param tierIds The strictly-increasing tier set defining the group.
+    /// @param token The token to fund with.
+    /// @param amount The amount to fund (ignored for native ETH — `msg.value` is used instead).
+    function fund(address hook, uint256[] calldata tierIds, IERC20 token, uint256 amount) external payable override {
+        // Derive the canonical group ID for the tier set.
+        uint256 groupId = _groupIdFor(tierIds);
+
+        // Record the tier set the first time a tier-scoped group is funded, so the stake math can scope it later.
+        if (groupId != 0 && _tierIdsOfGroup[hook][groupId].length == 0) {
+            _tierIdsOfGroup[hook][groupId] = tierIds;
+        }
 
-        // Materialize all unclaimed historical rewards into fresh vesting entries that start now.
-        _claimPastRewards({hook: hook, tokenIds: tokenIds, tokens: tokens});
+        _fund({hook: hook, groupId: groupId, token: token, amount: amount});
     }
 
-    /// @notice Collect already-vested rewards and first start vesting any unclaimed past reward rounds.
-    /// @param hook The 721 hook whose NFTs are collecting.
-    /// @param tokenIds The NFT token IDs to collect for.
-    /// @param tokens The reward tokens to collect.
-    /// @param beneficiary The recipient of collected vested rewards.
-    function collectVestedRewards(
+    /// @notice Recycle unclaimed rewards from expired tier-scoped reward rounds into the current reward round.
+    /// @param hook The 721 hook whose expired rewards should be recycled.
+    /// @param tierIds The strictly-increasing tier set defining the group.
+    /// @param token The reward token to recycle.
+    /// @param rounds The reward rounds to recycle.
+    /// @return amount The total amount recycled.
+    function burnExpiredRewards(
+        address hook,
+        uint256[] calldata tierIds,
+        IERC20 token,
+        uint256[] calldata rounds
+    )
+        external
+        override
+        returns (uint256 amount)
+    {
+        amount = _burnExpiredRewards({hook: hook, groupId: _groupIdFor(tierIds), token: token, rounds: rounds});
+    }
+
+    /// @notice Recycle unlocked rewards tied to burned NFTs in a tier-scoped group into the current reward round.
+    /// @dev Anyone can call this for burned tokens.
+    /// @param hook The 721 hook whose NFTs were burned.
+    /// @param tierIds The strictly-increasing tier set defining the group.
+    /// @param tokenIds The IDs of the burned NFTs (reverts if any are not actually burned).
+    /// @param tokens The reward tokens to recycle.
+    /// @param beneficiary Unused for forfeiture. Kept for interface compatibility.
+    function releaseForfeitedRewards(
         address hook,
+        uint256[] calldata tierIds,
         uint256[] calldata tokenIds,
         IERC20[] calldata tokens,
         address beneficiary
     )
-        public
-        override(JBDistributor, IJBDistributor)
+        external
+        override
     {
-        // Do not let reward-token callbacks mutate claim accounting during an inbound transfer.
-        _requireNotAcceptingToken();
-        if (tokenIds.length == 0) revert JBDistributor_EmptyTokenIds({tokenIdCount: tokenIds.length});
+        _releaseForfeitedRewards({
+            hook: hook, groupId: _groupIdFor(tierIds), tokenIds: tokenIds, tokens: tokens, beneficiary: beneficiary
+        });
+    }
 
-        // Only the current NFT owner can materialize and collect rewards for each token ID.
-        _requireCanClaimTokenIds({hook: hook, tokenIds: tokenIds});
+    //*********************************************************************//
+    // ----------------------- external views ---------------------------- //
+    //*********************************************************************//
 
-        // Before collecting, bring the token IDs current by starting vesting for any past reward rounds.
-        _claimPastRewards({hook: hook, tokenIds: tokenIds, tokens: tokens});
+    /// @notice Calculate the total uncollected (vesting + vested-but-uncollected) amount for an NFT token ID in a
+    /// tier-scoped group.
+    /// @param hook The 721 hook the tokenId belongs to.
+    /// @param tierIds The strictly-increasing tier set defining the group.
+    /// @param tokenId The ID of the NFT token to calculate for.
+    /// @param token The reward token to check.
+    /// @return tokenAmount The total uncollected amount (vesting + vested-but-uncollected).
+    function claimedFor(
+        address hook,
+        uint256[] calldata tierIds,
+        uint256 tokenId,
+        IERC20 token
+    )
+        external
+        view
+        override
+        returns (uint256 tokenAmount)
+    {
+        tokenAmount =
+            _unclaimedVestingAmountOf({hook: hook, groupId: _groupIdFor(tierIds), tokenId: tokenId, token: token});
+    }
+
+    /// @notice Calculate how much of a reward token is currently unlocked and ready to be collected for a given NFT
+    /// token ID in a tier-scoped group.
+    /// @param hook The 721 hook the tokenId belongs to.
+    /// @param tierIds The strictly-increasing tier set defining the group.
+    /// @param tokenId The ID of the NFT token to calculate for.
+    /// @param token The reward token to check.
+    /// @return tokenAmount The amount of tokens that can be collected right now via `collectVestedRewards`.
+    function collectableFor(
+        address hook,
+        uint256[] calldata tierIds,
+        uint256 tokenId,
+        IERC20 token
+    )
+        external
+        view
+        override
+        returns (uint256 tokenAmount)
+    {
+        tokenAmount = _collectableFor({hook: hook, groupId: _groupIdFor(tierIds), tokenId: tokenId, token: token});
+    }
+
+    /// @notice The tier set that defines a reward group, recorded when the group is first funded.
+    /// @param hook The 721 hook the group belongs to.
+    /// @param groupId The reward group.
+    /// @return tierIds The strictly-increasing tier set defining the group (empty for the all-tiers group, 0).
+    function tierIdsOf(address hook, uint256 groupId) external view override returns (uint256[] memory tierIds) {
+        tierIds = _tierIdsOfGroup[hook][groupId];
+    }
+
+    //*********************************************************************//
+    // ----------------------- public transactions ----------------------- //
+    //*********************************************************************//
+
+    /// @notice Begin vesting then collect everything unlocked for a tier-scoped reward group.
+    /// @param hook The 721 hook whose NFT owners are collecting.
+    /// @param tierIds The strictly-increasing tier set defining the group.
+    /// @param tokenIds The IDs of the NFTs to collect for (caller must be authorized for all of them).
+    /// @param tokens The reward tokens to collect vested amounts of.
+    /// @param beneficiary The recipient of the collected tokens.
+    function collectVestedRewards(
+        address hook,
+        uint256[] calldata tierIds,
+        uint256[] calldata tokenIds,
+        IERC20[] calldata tokens,
+        address beneficiary
+    )
+        external
+        override
+    {
+        _collectVestedRewards({
+            hook: hook, groupId: _groupIdFor(tierIds), tokenIds: tokenIds, tokens: tokens, beneficiary: beneficiary
+        });
+    }
 
-        // Release whatever portion of existing vesting entries has unlocked by this round.
-        _unlockRewards({hook: hook, tokenIds: tokenIds, tokens: tokens, beneficiary: beneficiary, ownerClaim: true});
+    /// @notice Borrow against one NFT token ID's uncollected vesting rewards in a tier-scoped group.
+    /// @param hook The 721 hook whose NFT owner is borrowing against vesting rewards.
+    /// @param tierIds The strictly-increasing tier set defining the group.
+    /// @param tokenIds The single NFT token ID to borrow against.
+    /// @param tokens The single revnet reward token to collateralize.
+    /// @param sourceToken The token to borrow from the revnet.
+    /// @param minBorrowAmount The minimum amount to borrow, denominated in `sourceToken`.
+    /// @param prepaidFeePercent The fee percent to charge upfront.
+    /// @param beneficiary The recipient of the borrowed funds.
+    /// @return loanId The Revnet loan NFT ID held by this distributor.
+    /// @return collateralCount The amount of vesting rewards used as collateral.
+    function borrowAgainstVesting(
+        address hook,
+        uint256[] calldata tierIds,
+        uint256[] calldata tokenIds,
+        IERC20[] calldata tokens,
+        address sourceToken,
+        uint256 minBorrowAmount,
+        uint256 prepaidFeePercent,
+        address payable beneficiary
+    )
+        external
+        override
+        returns (uint256 loanId, uint256 collateralCount)
+    {
+        (loanId, collateralCount) = _borrowAgainstVestingFor({
+            hook: hook,
+            groupId: _groupIdFor(tierIds),
+            tokenIds: tokenIds,
+            tokens: tokens,
+            sourceToken: sourceToken,
+            minBorrowAmount: minBorrowAmount,
+            prepaidFeePercent: prepaidFeePercent,
+            beneficiary: beneficiary
+        });
     }
 
     //*********************************************************************//
@@ -232,16 +393,31 @@ contract JB721Distributor is JBDistributor, IJB721Distributor {
 
     /// @notice Claim all past reward rounds for the given NFT token IDs and reward tokens into fresh vesting entries.
     /// @param hook The 721 hook whose NFT owners are claiming.
+    /// @param groupId The reward group being claimed (0 = all tiers).
     /// @param tokenIds The NFT token IDs to claim for.
     /// @param tokens The reward tokens to claim.
-    function _claimPastRewards(address hook, uint256[] calldata tokenIds, IERC20[] calldata tokens) internal override {
+    function _claimPastRewards(
+        address hook,
+        uint256 groupId,
+        uint256[] calldata tokenIds,
+        IERC20[] calldata tokens
+    )
+        internal
+        override
+    {
         // Round 0 has no completed reward rounds behind it, so nothing can be claimed yet.
         uint256 round = currentRound();
         if (round == 0) return;
 
-        // Current-round funding is excluded. It becomes claimable only after a later round starts.
-        JBClaimContext memory ctx =
-            JBClaimContext({hook: hook, lastClaimableRound: round - 1, vestingReleaseRound: round + VESTING_ROUNDS});
+        // Current-round funding is excluded. It becomes claimable only after a later round starts. For a tier-scoped
+        // group, load the tier set once so per-token eligibility can be checked without repeated storage reads.
+        JBClaimContext memory ctx = JBClaimContext({
+            hook: hook,
+            groupId: groupId,
+            tierIds: groupId == 0 ? new uint256[](0) : _tierIdsOfGroup[hook][groupId],
+            lastClaimableRound: round - 1,
+            vestingReleaseRound: round + VESTING_ROUNDS
+        });
 
         // Process each reward token independently because each token has its own round funding and claim cursor.
         for (uint256 i; i < tokens.length;) {
@@ -275,7 +451,7 @@ contract JB721Distributor is JBDistributor, IJB721Distributor {
 
         // Find the earliest cursor in the batch, skipping token IDs that are already current.
         for (uint256 i; i < tokenIds.length;) {
-            uint256 nextClaimRound = nextClaimRoundOf[ctx.hook][tokenIds[i]][token];
+            uint256 nextClaimRound = nextClaimRoundOf[ctx.hook][ctx.groupId][tokenIds[i]][token];
             if (nextClaimRound <= ctx.lastClaimableRound && nextClaimRound < firstClaimRound) {
                 firstClaimRound = nextClaimRound;
             }
@@ -291,17 +467,21 @@ contract JB721Distributor is JBDistributor, IJB721Distributor {
         // Walk every unclaimed historical round needed by at least one token ID.
         for (uint256 rewardRoundNumber = firstClaimRound; rewardRoundNumber <= ctx.lastClaimableRound;) {
             // Load this reward round's funding, snapshot, claim counter, and deadline.
-            JBRewardRoundData storage rewardRound = rewardRoundOf[ctx.hook][token][rewardRoundNumber];
+            JBRewardRoundData storage rewardRound = rewardRoundOf[ctx.hook][ctx.groupId][token][rewardRoundNumber];
 
             // Skip rounds that never received funding.
             if (rewardRound.amount != 0) {
                 // Expired rounds can no longer be claimed as-is; recycle their unclaimed remainder instead.
                 if (_rewardRoundExpired(rewardRound)) {
-                    _recycleExpiredRewardRound({hook: ctx.hook, token: token, round: rewardRoundNumber});
+                    _recycleExpiredRewardRound({
+                        hook: ctx.hook, groupId: ctx.groupId, token: token, round: rewardRoundNumber
+                    });
                 } else if (rewardRound.totalStake != 0) {
                     // Bundle the fixed round data used by every NFT in the batch.
                     JBVestContext memory vestCtx = JBVestContext({
                         hook: ctx.hook,
+                        groupId: ctx.groupId,
+                        tierIds: ctx.tierIds,
                         token: token,
                         distributable: rewardRound.amount,
                         totalStakeAmount: rewardRound.totalStake,
@@ -333,17 +513,18 @@ contract JB721Distributor is JBDistributor, IJB721Distributor {
         // Advance cursors even when a token ID earned zero, so empty or zero-stake rounds are not rescanned forever.
         for (uint256 i; i < tokenIds.length;) {
             uint256 tokenId = tokenIds[i];
-            nextClaimRoundOf[ctx.hook][tokenId][token] = ctx.lastClaimableRound + 1;
+            nextClaimRoundOf[ctx.hook][ctx.groupId][tokenId][token] = ctx.lastClaimableRound + 1;
 
             // All accumulated past rewards for this NFT start a single fresh vesting schedule at the claim round.
             if (tokenAmounts[i] != 0) {
-                vestingDataOf[ctx.hook][tokenId][token].push(
+                vestingDataOf[ctx.hook][ctx.groupId][tokenId][token].push(
                     JBVestingData({releaseRound: ctx.vestingReleaseRound, amount: tokenAmounts[i], shareClaimed: 0})
                 );
 
                 emit Claimed({
                     hook: ctx.hook,
                     tokenId: tokenId,
+                    groupId: ctx.groupId,
                     token: token,
                     amount: tokenAmounts[i],
                     vestingReleaseRound: ctx.vestingReleaseRound,
@@ -370,6 +551,31 @@ contract JB721Distributor is JBDistributor, IJB721Distributor {
         internal
         returns (uint256 totalVestingAmount)
     {
+        // Tier-scoped groups distribute a tier's pot among that tier's eligible NFTs. Each NFT contributes its tier's
+        // voting units, with no per-owner cap: the denominator (summed `getPastTierVotingUnits`) counts exactly those
+        // eligible NFTs, so the shares reconcile without the all-tiers delegation-cap machinery.
+        if (ctx.groupId != 0) {
+            for (uint256 j; j < tokenIds.length;) {
+                if (nextClaimRoundOf[ctx.hook][ctx.groupId][tokenIds[j]][ctx.token] <= ctx.rewardRound) {
+                    uint256 stake = _tierScopedStake({ctx: ctx, tokenId: tokenIds[j]});
+                    if (stake != 0) {
+                        uint256 tokenAmount =
+                            mulDiv({x: ctx.distributable, y: stake, denominator: ctx.totalStakeAmount});
+                        tokenAmounts[j] += tokenAmount;
+                        totalVestingAmount += tokenAmount;
+                    }
+                }
+
+                unchecked {
+                    ++j;
+                }
+            }
+
+            return totalVestingAmount;
+        }
+
+        // All-tiers group (0): split the pot pro-rata across delegated voting power, capping each owner so multiple
+        // NFTs cannot over-claim beyond the owner's checkpointed votes.
         // Allocate scratch arrays sized to the maximum possible number of distinct snapshot owners.
         address[] memory owners = new address[](tokenIds.length);
         uint256[] memory consumed = new uint256[](tokenIds.length);
@@ -377,7 +583,7 @@ contract JB721Distributor is JBDistributor, IJB721Distributor {
 
         // Claim each token ID that has not yet advanced past this reward round.
         for (uint256 j; j < tokenIds.length;) {
-            if (nextClaimRoundOf[ctx.hook][tokenIds[j]][ctx.token] <= ctx.rewardRound) {
+            if (nextClaimRoundOf[ctx.hook][0][tokenIds[j]][ctx.token] <= ctx.rewardRound) {
                 (uint256 tokenAmount, uint256 newUniqueCount) = _claimRewardRoundForTokenId({
                     ctx: ctx, tokenId: tokenIds[j], owners: owners, consumed: consumed, uniqueCount: uniqueCount
                 });
@@ -473,75 +679,6 @@ contract JB721Distributor is JBDistributor, IJB721Distributor {
         consumed[ownerIndex] += stake;
     }
 
-    /// @notice Override vesting to cap each owner's consumed voting power across all their NFTs.
-    /// @dev Prevents an owner with N NFTs of V voting units each from claiming N*V when their pastVotes < N*V.
-    ///      Iterates over all token IDs in the batch, delegating per-token logic to `_vestSingleToken`. A pair of
-    ///      scratch arrays (`owners` and `consumed`) tracks how much voting power each distinct owner has used so far,
-    ///      ensuring the aggregate claim never exceeds the owner's snapshot voting power.
-    ///      Silently skips burned tokens, already-vested tokens, and tokens whose owner had no snapshot voting power.
-    /// @param hook The address of the 721 hook whose stakers are vesting.
-    /// @param tokenIds The NFT token IDs to vest rewards for.
-    /// @param token The ERC-20 reward token to distribute.
-    /// @param distributable The total distributable amount of `token` for this round.
-    /// @param totalStakeAmount The aggregate voting power at the round's snapshot block.
-    /// @param vestingReleaseRound The round number at which the vesting period ends and tokens become fully claimable.
-    /// @return totalVestingAmount The sum of reward tokens that began vesting across all processed token IDs.
-    function _vestTokenIds(
-        address hook,
-        uint256[] calldata tokenIds,
-        IERC20 token,
-        uint256 distributable,
-        uint256 totalStakeAmount,
-        uint256 vestingReleaseRound
-    )
-        internal
-        override
-        returns (uint256 totalVestingAmount)
-    {
-        // Bundle iteration-constant parameters into a struct to avoid stack-too-deep errors.
-        JBVestContext memory ctx = JBVestContext({
-            hook: hook,
-            token: token,
-            distributable: distributable,
-            totalStakeAmount: totalStakeAmount,
-            vestingReleaseRound: vestingReleaseRound,
-            rewardRound: currentRound(),
-            snapshotBlock: roundSnapshotBlock[currentRound()]
-        });
-
-        // Allocate scratch arrays sized to the maximum possible number of distinct owners (one per token ID).
-        address[] memory owners = new address[](tokenIds.length);
-        uint256[] memory consumed = new uint256[](tokenIds.length);
-
-        // Track how many distinct owners have been recorded in the scratch arrays so far.
-        uint256 uniqueCount;
-
-        // Iterate over every token ID in the batch.
-        for (uint256 j; j < tokenIds.length;) {
-            // Vest the single token, receiving its reward amount and the updated distinct owner count.
-            (uint256 tokenAmount, uint256 newUniqueCount) = _vestSingleToken({
-                ctx: ctx, tokenId: tokenIds[j], owners: owners, consumed: consumed, uniqueCount: uniqueCount
-            });
-
-            // Carry the updated owner count forward so subsequent tokens can reference the same tracking data.
-            uniqueCount = newUniqueCount;
-
-            unchecked {
-                // Accumulate the individual token's reward into the batch-wide total.
-                totalVestingAmount += tokenAmount;
-                ++j;
-            }
-        }
-
-        // Persist consumed voting power to storage to prevent cap resets across calls.
-        for (uint256 k; k < uniqueCount;) {
-            _consumedVotesOf[hook][token][ctx.rewardRound][owners[k]] = consumed[k];
-            unchecked {
-                ++k;
-            }
-        }
-    }
-
     //*********************************************************************//
     // ----------------------- internal views ---------------------------- //
     //*********************************************************************//
@@ -555,6 +692,37 @@ contract JB721Distributor is JBDistributor, IJB721Distributor {
         canClaim = IERC721(hook).ownerOf(tokenId) == account;
     }
 
+    /// @notice Derive the canonical group ID for a tier set. The empty set is the all-tiers group (0).
+    /// @param tierIds Strictly-increasing tier IDs; empty for the all-tiers group.
+    /// @return groupId 0 for the all-tiers group, else `keccak256(abi.encode(tierIds))`.
+    function _groupIdFor(uint256[] calldata tierIds) internal pure returns (uint256 groupId) {
+        if (tierIds.length == 0) return 0;
+        for (uint256 i = 1; i < tierIds.length;) {
+            if (tierIds[i] <= tierIds[i - 1]) {
+                revert JB721Distributor_TierIdsNotIncreasing({previousTierId: tierIds[i - 1], tierId: tierIds[i]});
+            }
+            unchecked {
+                ++i;
+            }
+        }
+        groupId = uint256(keccak256(abi.encode(tierIds)));
+    }
+
+    /// @notice Whether a tier ID is present in a strictly-increasing tier set.
+    /// @param tierId The tier ID to look for.
+    /// @param tierIds The strictly-increasing tier set to search.
+    /// @return found True if `tierId` is in `tierIds`.
+    function _isTierInSet(uint256 tierId, uint256[] memory tierIds) internal pure returns (bool found) {
+        for (uint256 i; i < tierIds.length;) {
+            if (tierIds[i] == tierId) return true;
+            // The set is strictly increasing, so once an entry exceeds the target it cannot appear later.
+            if (tierIds[i] > tierId) return false;
+            unchecked {
+                ++i;
+            }
+        }
+    }
+
     /// @notice Revert unless the caller is authorized to claim each NFT token ID.
     /// @param hook The 721 hook whose NFT owners are claiming.
     /// @param tokenIds The NFT token IDs to check.
@@ -577,6 +745,30 @@ contract JB721Distributor is JBDistributor, IJB721Distributor {
         }
     }
 
+    /// @notice The tier-scoped stake of a single NFT in a reward round: its tier's voting units if the NFT's tier is
+    /// in the group's set and the NFT existed at the round snapshot, else zero.
+    /// @dev No per-owner cap is applied. Eligibility (`ownerOfAt != 0`) plus tier membership matches exactly the set
+    /// counted by the `getPastTierVotingUnits` denominator, so per-NFT shares reconcile against the pot.
+    /// @param ctx The reward-round context (carries the group's tier set and snapshot block).
+    /// @param tokenId The NFT token ID to weigh.
+    /// @return stake The NFT's tier voting units, or 0 if ineligible.
+    function _tierScopedStake(JBVestContext memory ctx, uint256 tokenId) internal view returns (uint256 stake) {
+        // The NFT's tier must be one of the funded tiers.
+        uint256 tierId = IJB721TiersHook(ctx.hook).STORE().tierIdOfToken(tokenId);
+        if (!_isTierInSet({tierId: tierId, tierIds: ctx.tierIds})) return 0;
+
+        // The NFT must have existed at the round snapshot block (proven via the checkpoint owner history).
+        if (_snapshotOwnerOf({hook: ctx.hook, tokenId: tokenId, snapshotBlock: ctx.snapshotBlock}) == address(0)) {
+            return 0;
+        }
+
+        // Eligible: weigh the NFT by its tier's voting units.
+        stake =
+        IJB721TiersHook(ctx.hook)
+        .STORE()
+        .tierOfTokenId({hook: ctx.hook, tokenId: tokenId, includeResolvedUri: false}).votingUnits;
+    }
+
     /// @notice Checks if the given token was burned.
     /// @param hook The hook the token belongs to.
     /// @param tokenId The tokenId to check.
@@ -620,16 +812,39 @@ contract JB721Distributor is JBDistributor, IJB721Distributor {
         tokenStakeAmount = votingUnits < pastVotes ? votingUnits : pastVotes;
     }
 
-    /// @notice The total stake at a specific block, using the hook's checkpoints module for historical accuracy.
-    /// @dev Uses `IVotes.getPastTotalSupply` from the hook's checkpoints module. This ensures that only NFTs
-    /// that existed (and were delegated) at `blockNumber` are counted, preventing late mints from diluting or
-    /// capturing rewards within the current round.
+    /// @notice The total stake sharing a group's round rewards at a specific block.
+    /// @dev For the all-tiers group (0) this is `getPastTotalSupply` from the hook's checkpoints module (all NFTs that
+    /// existed and were delegated at `blockNumber`). For a tier-scoped group it is the summed
+    /// `getPastTierVotingUnits` over the group's tier set — the eligible voting units of those tiers at the snapshot.
     /// @param hook The hook to get the total stake for.
+    /// @param groupId The reward group (0 = all tiers).
     /// @param blockNumber The block number to get the total staked amount at.
-    /// @return total The total checkpointed voting units at the given block.
-    function _totalStake(address hook, uint256 blockNumber) internal view override returns (uint256 total) {
+    /// @return total The total stake at the given block.
+    function _totalStake(
+        address hook,
+        uint256 groupId,
+        uint256 blockNumber
+    )
+        internal
+        view
+        override
+        returns (uint256 total)
+    {
         IJB721Checkpoints checkpoints = IJB721TiersHook(hook).checkpoints();
-        total = IVotes(address(checkpoints)).getPastTotalSupply(blockNumber);
+
+        // All-tiers group (0): the global checkpointed voting supply.
+        if (groupId == 0) {
+            return IVotes(address(checkpoints)).getPastTotalSupply(blockNumber);
+        }
+
+        // Tier-scoped group: sum the eligible voting units of each tier in the set at the snapshot block.
+        uint256[] memory tierIds = _tierIdsOfGroup[hook][groupId];
+        for (uint256 i; i < tierIds.length;) {
+            total += checkpoints.getPastTierVotingUnits({tierId: tierIds[i], blockNumber: blockNumber});
+            unchecked {
+                ++i;
+            }
+        }
     }
 
     //*********************************************************************//
@@ -664,132 +879,4 @@ contract JB721Distributor is JBDistributor, IJB721Distributor {
         // A zero owner means the token was not owned at the snapshot block and is not eligible this round.
         owner = abi.decode(data, (address));
     }
-
-    /// @notice Vest a single NFT token, enforcing a per-owner voting power cap across the batch.
-    /// @dev Returns 0 for burned tokens, already-vested tokens, tokens whose owner had no snapshot voting power,
-    ///      and tokens whose owner has already exhausted their voting power cap within this batch.
-    ///      The `owners` and `consumed` arrays form a compact map that tracks how much voting power each unique
-    ///      owner has consumed so far. `uniqueCount` tracks how many slots are used.
-    /// @param ctx The vesting context containing hook address, reward token, distributable amount, total stake,
-    ///        and release round.
-    /// @param tokenId The NFT token ID to process.
-    /// @param owners A scratch array mapping slot indices to owner addresses for deduplication within this batch.
-    /// @param consumed A scratch array tracking how much voting power each owner (by slot index) has consumed.
-    /// @param uniqueCount The number of distinct owners seen so far in the batch.
-    /// @return tokenAmount The reward amount vested for this token ID (0 if skipped).
-    /// @return newUniqueCount The updated count of distinct owners after processing this token ID.
-    function _vestSingleToken(
-        JBVestContext memory ctx,
-        uint256 tokenId,
-        address[] memory owners,
-        uint256[] memory consumed,
-        uint256 uniqueCount
-    )
-        private
-        returns (uint256 tokenAmount, uint256 newUniqueCount)
-    {
-        // Initialize the return value to the current count of distinct owners.
-        newUniqueCount = uniqueCount;
-
-        // Skip burned tokens — they are excluded from _totalStake, so including them would overbook vesting.
-        if (_tokenBurned({hook: ctx.hook, tokenId: tokenId})) return (0, newUniqueCount);
-
-        // Skip already-vested tokenIds — check if the last vesting entry targets the same release round.
-        {
-            // Load the number of existing vesting entries for this token.
-            JBVestingData[] storage vestings = vestingDataOf[ctx.hook][tokenId][ctx.token];
-            uint256 numVesting = vestings.length;
-
-            // If at least one entry exists and its release round matches, this token was already vested this round.
-            if (numVesting != 0 && vestings[numVesting - 1].releaseRound == ctx.vestingReleaseRound) {
-                return (0, newUniqueCount);
-            }
-        }
-
-        // Look up the NFT's voting units from its tier in the hook's store.
-        uint256 votingUnits =
-            IJB721TiersHook(ctx.hook)
-        .STORE()
-        .tierOfTokenId({hook: ctx.hook, tokenId: tokenId, includeResolvedUri: false}).votingUnits;
-
-        // Look up the snapshot owner, verify snapshot eligibility, and find or create the owner's tracking slot.
-        uint256 ownerIndex;
-        uint256 pastVotes;
-        {
-            // Reuse the same round snapshot block for every token in this vesting batch.
-            uint256 snapshotBlock = ctx.snapshotBlock;
-            address owner = _snapshotOwnerOf({hook: ctx.hook, tokenId: tokenId, snapshotBlock: snapshotBlock});
-            if (owner == address(0)) return (0, newUniqueCount);
-
-            // Query the owner's checkpointed voting power at the round's snapshot block.
-            pastVotes = IVotes(address(IJB721TiersHook(ctx.hook).checkpoints()))
-                .getPastVotes({account: owner, timepoint: snapshotBlock});
-
-            // If the snapshot owner had no voting power at the snapshot block, the token is ineligible for this round.
-            if (pastVotes == 0) return (0, newUniqueCount);
-
-            // Search the owners array for an existing slot belonging to this owner.
-            bool found;
-            for (uint256 k; k < newUniqueCount;) {
-                if (owners[k] == owner) {
-                    // Re-use the existing tracking slot for this owner.
-                    ownerIndex = k;
-                    found = true;
-                    break;
-                }
-                unchecked {
-                    ++k;
-                }
-            }
-
-            // If no existing slot was found, allocate a new one at the end of the arrays.
-            if (!found) {
-                ownerIndex = newUniqueCount;
-                owners[newUniqueCount] = owner;
-                // Initialize from persistent storage to prevent cap resets across calls.
-                consumed[newUniqueCount] = _consumedVotesOf[ctx.hook][ctx.token][ctx.rewardRound][owner];
-                unchecked {
-                    ++newUniqueCount;
-                }
-            }
-        }
-
-        // Cap this NFT's effective stake at the owner's remaining voting power budget for this batch.
-        uint256 stake;
-        {
-            // Calculate how much voting power the owner has left after prior tokens in this batch.
-            uint256 remaining = pastVotes > consumed[ownerIndex] ? pastVotes - consumed[ownerIndex] : 0;
-
-            // The effective stake is the lesser of the NFT's voting units and the owner's remaining budget.
-            stake = votingUnits < remaining ? votingUnits : remaining;
-        }
-
-        // If the effective stake is zero, the owner's budget is exhausted — skip this token.
-        if (stake == 0) return (0, newUniqueCount);
-
-        // Calculate the pro-rata reward amount: (distributable * stake) / totalStakeAmount.
-        tokenAmount = mulDiv({x: ctx.distributable, y: stake, denominator: ctx.totalStakeAmount});
-
-        // If the pro-rata amount rounds to zero, do not consume the owner's voting budget.
-        if (tokenAmount == 0) return (0, newUniqueCount);
-
-        // Record that this owner has consumed additional voting power from their budget.
-        consumed[ownerIndex] += stake;
-
-        // Only create a vesting entry and emit an event if there is a non-zero reward.
-        // Push a new vesting data entry for this token ID, starting with zero shareClaimed.
-        vestingDataOf[ctx.hook][tokenId][ctx.token].push(
-            JBVestingData({releaseRound: ctx.vestingReleaseRound, amount: tokenAmount, shareClaimed: 0})
-        );
-
-        // Emit the claim event for off-chain indexers.
-        emit Claimed({
-            hook: ctx.hook,
-            tokenId: tokenId,
-            token: ctx.token,
-            amount: tokenAmount,
-            vestingReleaseRound: ctx.vestingReleaseRound,
-            caller: msg.sender
-        });
-    }
 }