@bananapus/distributor-v6 0.0.33 → 0.0.35

package/src/JBDistributor.sol

@@ -20,7 +20,6 @@ import {IJBDistributor} from "./interfaces/IJBDistributor.sol";
 import {JBVestingMath} from "./libraries/JBVestingMath.sol";
 import {JBBorrowContext} from "./structs/JBBorrowContext.sol";
 import {JBRewardRoundData} from "./structs/JBRewardRoundData.sol";
-import {JBTokenSnapshotData} from "./structs/JBTokenSnapshotData.sol";
 import {JBVestingData} from "./structs/JBVestingData.sol";
 import {JBVestingLoan} from "./structs/JBVestingLoan.sol";
 
@@ -59,9 +58,6 @@ abstract contract JBDistributor is IJBDistributor {
     /// @notice Thrown when the caller does not have access to the token.
     error JBDistributor_NoAccess(address hook, uint256 tokenId, address account);
 
-    /// @notice Thrown when there is nothing to distribute for a token in the current round.
-    error JBDistributor_NothingToDistribute(address hook, address token, uint256 round);
-
     /// @notice Thrown when there are no uncollected vesting revnet tokens to collateralize a loan.
     error JBDistributor_NothingToBorrow(address hook, address token);
 
@@ -147,17 +143,23 @@ abstract contract JBDistributor is IJBDistributor {
 
     /// @notice The active Revnet loan using one token ID's vesting rewards as collateral.
     /// @custom:param hook The hook the token ID belongs to.
+    /// @custom:param groupId The reward group (0 = the default group).
     /// @custom:param tokenId The token ID whose vesting rewards are collateralized.
     /// @custom:param token The reward token used as loan collateral.
-    mapping(address hook => mapping(uint256 tokenId => mapping(IERC20 token => uint256)))
+    mapping(
+        address hook => mapping(uint256 groupId => mapping(uint256 tokenId => mapping(IERC20 token => uint256)))
+    )
         public
         override activeVestingLoanIdOf;
 
     /// @notice The index within `vestingDataOf` of the latest vest.
     /// @custom:param hook The hook the tokenId belongs to.
+    /// @custom:param groupId The reward group (0 = the default group).
     /// @custom:param tokenId The ID of the token to which the vests belong.
     /// @custom:param token The address of the token vested.
-    mapping(address hook => mapping(uint256 tokenId => mapping(IERC20 token => uint256))) public latestVestedIndexOf;
+    mapping(
+        address hook => mapping(uint256 groupId => mapping(uint256 tokenId => mapping(IERC20 token => uint256)))
+    ) public latestVestedIndexOf;
 
     /// @notice The block number recorded as the snapshot point for each round.
     /// @dev Set to `block.number - 1` on first interaction in a round, so that `IVotes.getPastVotes` works.
@@ -165,9 +167,12 @@ abstract contract JBDistributor is IJBDistributor {
 
     /// @notice Reward data assigned to each funding round.
     /// @custom:param hook The stake source whose stakers receive rewards.
+    /// @custom:param groupId The reward group (0 = the default group).
     /// @custom:param token The reward token.
     /// @custom:param round The reward round.
-    mapping(address hook => mapping(IERC20 token => mapping(uint256 round => JBRewardRoundData))) public rewardRoundOf;
+    mapping(
+        address hook => mapping(uint256 groupId => mapping(IERC20 token => mapping(uint256 round => JBRewardRoundData)))
+    ) public rewardRoundOf;
 
     /// @notice The amount of a token that is currently vesting for a hook's stakers.
     /// @custom:param hook The hook whose stakers are vesting.
@@ -181,9 +186,12 @@ abstract contract JBDistributor is IJBDistributor {
 
     /// @notice All vesting data of a tokenId for any number of vesting tokens.
     /// @custom:param hook The hook the tokenId belongs to.
+    /// @custom:param groupId The reward group (0 = the default group).
     /// @custom:param tokenId The ID of the token to which the vests belong.
     /// @custom:param token The address of the token vested.
-    mapping(address hook => mapping(uint256 tokenId => mapping(IERC20 token => JBVestingData[]))) public vestingDataOf;
+    mapping(
+        address hook => mapping(uint256 groupId => mapping(uint256 tokenId => mapping(IERC20 token => JBVestingData[])))
+    ) public vestingDataOf;
 
     //*********************************************************************//
     // -------------------- internal stored properties ------------------- //
@@ -202,21 +210,6 @@ abstract contract JBDistributor is IJBDistributor {
     /// @custom:param loanId The Revnet loan NFT ID.
     mapping(uint256 loanId => JBVestingLoan) internal _vestingLoanOf;
 
-    /// @notice The snapshot data of the token information for each round.
-    /// @custom:param hook The hook the snapshot is for.
-    /// @custom:param token The address of the token claimed and vested.
-    /// @custom:param round The round to which the data applies.
-    mapping(address hook => mapping(IERC20 token => mapping(uint256 round => JBTokenSnapshotData snapshot))) internal
-        _snapshotAtRoundOf;
-
-    /// @notice Whether a snapshot has been taken for a given (hook, token, round).
-    /// @dev Required because a snapshot can legitimately store `{balance: 0, vestingAmount: 0}`,
-    /// so a zero balance is not a usable sentinel for "uninitialized".
-    /// @custom:param hook The hook the snapshot is for.
-    /// @custom:param token The address of the token claimed and vested.
-    /// @custom:param round The round to which the data applies.
-    mapping(address hook => mapping(IERC20 token => mapping(uint256 round => bool))) internal _snapshotInitializedFor;
-
     //*********************************************************************//
     // ------------------- transient stored properties ------------------- //
     //*********************************************************************//
@@ -271,9 +264,11 @@ abstract contract JBDistributor is IJBDistributor {
     // ---------------------- external transactions ---------------------- //
     //*********************************************************************//
 
-    /// @notice Snapshot the current round's distributable balance and begin vesting for the specified token IDs.
-    /// Each token ID's share is proportional to its stake weight relative to the total stake at the snapshot block.
-    /// Vesting completes after `VESTING_ROUNDS` rounds. Reverts if there's nothing to distribute.
+    /// @notice Begin vesting all unclaimed past reward rounds for the specified token IDs.
+    /// @dev Materializes each token ID's pro-rata share of every past (non-current) reward round into fresh vesting
+    /// entries that start now and unlock over `VESTING_ROUNDS`. Current-round funding is excluded until a later round
+    /// starts. The model-specific per-round claim math and the authorization check live in the `_claimPastRewards`
+    /// and `_requireCanClaimTokenIds` hooks each concrete distributor implements.
     /// @param hook The hook (IVotes token or 721 hook) whose stakers are vesting.
     /// @param tokenIds The staker token IDs to claim rewards for.
     /// @param tokens The reward tokens to begin vesting.
@@ -286,56 +281,7 @@ abstract contract JBDistributor is IJBDistributor {
         virtual
         override
     {
-        // Reward accounting cannot change while an ERC-20 `transferFrom` is in progress. A callback-capable reward
-        // token could otherwise snapshot, vest, or collect against balances between `balanceBefore` and
-        // `balanceAfter`, distorting the delta credited to the funder.
-        _requireNotAcceptingToken();
-
-        // Revert if no token IDs are provided.
-        if (tokenIds.length == 0) revert JBDistributor_EmptyTokenIds({tokenIdCount: tokenIds.length});
-
-        // Keep a reference to the current round.
-        uint256 round = currentRound();
-
-        // Ensure the snapshot block is recorded for this round.
-        _ensureSnapshotBlock(round);
-
-        // Keep a reference to the total staked amount at the snapshot block.
-        uint256 totalStakeAmount = _totalStake({hook: hook, blockNumber: roundSnapshotBlock[round]});
-
-        // Skip vesting when there are no stakers — funds carry over to the next round.
-        if (totalStakeAmount == 0) return;
-
-        // Loop through each token for which vesting is beginning.
-        for (uint256 i; i < tokens.length;) {
-            IERC20 token = tokens[i];
-
-            // Take a snapshot of the token balance if it hasn't been taken already.
-            JBTokenSnapshotData memory snapshot = _takeSnapshotOf({hook: hook, token: token});
-            uint256 distributable = snapshot.balance - snapshot.vestingAmount;
-
-            // Revert if there is nothing to distribute for this token.
-            if (distributable == 0) {
-                revert JBDistributor_NothingToDistribute({hook: hook, token: address(token), round: round});
-            }
-
-            // Vest each token ID and get the total amount vested.
-            uint256 totalVestingAmount = _vestTokenIds({
-                hook: hook,
-                tokenIds: tokenIds,
-                token: token,
-                distributable: distributable,
-                totalStakeAmount: totalStakeAmount,
-                vestingReleaseRound: round + VESTING_ROUNDS
-            });
-
-            unchecked {
-                // Store the updated total claimed amount now vesting.
-                totalVestingAmountOf[hook][token] += totalVestingAmount;
-
-                ++i;
-            }
-        }
+        _beginVesting({hook: hook, groupId: 0, tokenIds: tokenIds, tokens: tokens});
     }
 
     /// @notice Directly fund the distributor for a specific hook by pulling tokens from the caller. An alternative
@@ -346,7 +292,7 @@ abstract contract JBDistributor is IJBDistributor {
     /// @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, IERC20 token, uint256 amount) external payable virtual override {
-        _fund({hook: hook, token: token, amount: amount});
+        _fund({hook: hook, groupId: 0, token: token, amount: amount});
     }
 
     /// @notice Recycle unclaimed rewards from expired reward rounds into the current reward round.
@@ -365,19 +311,7 @@ abstract contract JBDistributor is IJBDistributor {
         override
         returns (uint256 amount)
     {
-        // Do not let reward-token callbacks recycle inventory during an inbound balance-delta measurement.
-        _requireNotAcceptingToken();
-
-        // Process every requested round independently so callers can batch keeper work.
-        for (uint256 i; i < rounds.length;) {
-            // Add this round's expired remainder to the batch total.
-            amount += _recycleExpiredRewardRound({hook: hook, token: token, round: rounds[i]});
-
-            unchecked {
-                // Safe because the loop is bounded by calldata length.
-                ++i;
-            }
-        }
+        amount = _burnExpiredRewards({hook: hook, groupId: 0, token: token, rounds: rounds});
     }
 
     /// @notice Record the snapshot block for the current round (and eagerly for the next round). Callable by anyone —
@@ -401,21 +335,7 @@ abstract contract JBDistributor is IJBDistributor {
         external
         override
     {
-        // Do not let reward-token callbacks mutate vesting state during inbound balance-delta accounting.
-        _requireNotAcceptingToken();
-
-        // Make sure that all staker token IDs are burned.
-        for (uint256 i; i < tokenIds.length;) {
-            if (!_tokenBurned({hook: hook, tokenId: tokenIds[i]})) {
-                revert JBDistributor_NoAccess({hook: hook, tokenId: tokenIds[i], account: msg.sender});
-            }
-            unchecked {
-                ++i;
-            }
-        }
-
-        // Unlock the rewards and recycle the forfeited amount.
-        _unlockRewards({hook: hook, tokenIds: tokenIds, tokens: tokens, beneficiary: beneficiary, ownerClaim: false});
+        _releaseForfeitedRewards({hook: hook, groupId: 0, tokenIds: tokenIds, tokens: tokens, beneficiary: beneficiary});
     }
 
     //*********************************************************************//
@@ -445,7 +365,7 @@ abstract contract JBDistributor is IJBDistributor {
         override
         returns (uint256 tokenAmount)
     {
-        tokenAmount = _unclaimedVestingAmountOf({hook: hook, tokenId: tokenId, token: token});
+        tokenAmount = _unclaimedVestingAmountOf({hook: hook, groupId: 0, tokenId: tokenId, token: token});
     }
 
     /// @notice Calculate how much of a reward token is currently unlocked and ready to be collected for a given
@@ -464,63 +384,7 @@ abstract contract JBDistributor is IJBDistributor {
         override
         returns (uint256 tokenAmount)
     {
-        // A loan keeps this token ID's vesting rewards in collateral custody until the loan is repaid.
-        if (activeVestingLoanIdOf[hook][tokenId][token] != 0) return 0;
-
-        // The round that we are in right now.
-        uint256 round = currentRound();
-
-        // Keep a reference to the latest vested index.
-        uint256 vestedIndex = latestVestedIndexOf[hook][tokenId][token];
-
-        // Keep a reference to the vesting data array.
-        JBVestingData[] storage vestings = vestingDataOf[hook][tokenId][token];
-        uint256 numberOfVestingRounds = vestings.length;
-
-        while (vestedIndex < numberOfVestingRounds) {
-            uint256 lockedShare;
-
-            // Keep a reference to the vested data being iterated on.
-            JBVestingData memory vesting = vestings[vestedIndex];
-
-            lockedShare = JBVestingMath.lockedShareOf({
-                releaseRound: vesting.releaseRound,
-                currentRound: round,
-                vestingRounds: VESTING_ROUNDS,
-                maxShare: MAX_SHARE
-            });
-
-            // Calculate the newly unlocked amount from cumulative shares rather than the incremental share delta.
-            // Incremental floor rounding can otherwise underpay partial collections and leave dust stranded.
-            (uint256 claimAmount,) = JBVestingMath.newlyClaimableAmountOf({
-                amount: vesting.amount,
-                shareClaimed: vesting.shareClaimed,
-                lockedShare: lockedShare,
-                maxShare: MAX_SHARE
-            });
-            tokenAmount += claimAmount;
-
-            unchecked {
-                ++vestedIndex;
-            }
-        }
-    }
-
-    /// @notice The snapshot data of the token information for each round.
-    /// @param hook The hook the snapshot is for.
-    /// @param token The address of the token claimed and vested.
-    /// @param round The round to which the data applies.
-    function snapshotAtRoundOf(
-        address hook,
-        IERC20 token,
-        uint256 round
-    )
-        external
-        view
-        override
-        returns (JBTokenSnapshotData memory)
-    {
-        return _snapshotAtRoundOf[hook][token][round];
+        tokenAmount = _collectableFor({hook: hook, groupId: 0, tokenId: tokenId, token: token});
     }
 
     /// @notice The vesting position collateralized by a Revnet loan.
@@ -548,11 +412,12 @@ abstract contract JBDistributor is IJBDistributor {
     // ----------------------- public transactions ----------------------- //
     //*********************************************************************//
 
-    /// @notice Collect tokens that have vested (partially or fully) and transfer them to the beneficiary. Also
-    /// auto-vests for the current round if rewards haven't been claimed yet — so callers don't need to separately
-    /// call `beginVesting`. Only the token owner (verified via `_canClaim`) can collect.
+    /// @notice Begin vesting any unclaimed past reward rounds, then collect everything that has since unlocked and
+    /// transfer it to the beneficiary — so callers don't need to separately call `beginVesting`.
+    /// @dev The model-specific per-round claim math and the authorization check live in the `_claimPastRewards`
+    /// and `_requireCanClaimTokenIds` hooks each concrete distributor implements.
     /// @param hook The hook whose stakers are collecting.
-    /// @param tokenIds The IDs of the tokens to collect for (caller must own all of them).
+    /// @param tokenIds The IDs of the tokens 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(
@@ -565,63 +430,7 @@ abstract contract JBDistributor is IJBDistributor {
         virtual
         override
     {
-        // Collections transfer reward tokens out. If this runs inside the same reward token's inbound transfer, the
-        // outgoing transfer can net against the incoming balance delta and strand the new funds unaccounted.
-        _requireNotAcceptingToken();
-
-        // Revert if no token IDs are provided.
-        if (tokenIds.length == 0) revert JBDistributor_EmptyTokenIds({tokenIdCount: tokenIds.length});
-
-        // Make sure that all tokens can be claimed by this sender.
-        for (uint256 i; i < tokenIds.length;) {
-            if (!_canClaim({hook: hook, tokenId: tokenIds[i], account: msg.sender})) {
-                revert JBDistributor_NoAccess({hook: hook, tokenId: tokenIds[i], account: msg.sender});
-            }
-            unchecked {
-                ++i;
-            }
-        }
-
-        // --- Auto-vest for the current round ---
-        uint256 round = currentRound();
-
-        // Ensure the snapshot block is recorded for this round.
-        _ensureSnapshotBlock(round);
-
-        // Keep a reference to the total staked amount at the snapshot block.
-        uint256 totalStakeAmount = _totalStake({hook: hook, blockNumber: roundSnapshotBlock[round]});
-
-        // Loop through each token and auto-vest if there's something distributable.
-        for (uint256 i; i < tokens.length;) {
-            IERC20 token = tokens[i];
-
-            // Take a snapshot of the token balance if it hasn't been taken already.
-            JBTokenSnapshotData memory snapshot = _takeSnapshotOf({hook: hook, token: token});
-            uint256 distributable = snapshot.balance - snapshot.vestingAmount;
-
-            // Only auto-vest if there's something to distribute and there's stake.
-            if (distributable > 0 && totalStakeAmount > 0) {
-                uint256 totalVestingAmount = _vestTokenIds({
-                    hook: hook,
-                    tokenIds: tokenIds,
-                    token: token,
-                    distributable: distributable,
-                    totalStakeAmount: totalStakeAmount,
-                    vestingReleaseRound: round + VESTING_ROUNDS
-                });
-
-                unchecked {
-                    totalVestingAmountOf[hook][token] += totalVestingAmount;
-                }
-            }
-
-            unchecked {
-                ++i;
-            }
-        }
-
-        // Unlock the rewards and send them to the beneficiary.
-        _unlockRewards({hook: hook, tokenIds: tokenIds, tokens: tokens, beneficiary: beneficiary, ownerClaim: true});
+        _collectVestedRewards({hook: hook, groupId: 0, tokenIds: tokenIds, tokens: tokens, beneficiary: beneficiary});
     }
 
     /// @notice Borrow from a revnet using one token ID's uncollected vesting rewards as collateral.
@@ -650,41 +459,16 @@ abstract contract JBDistributor is IJBDistributor {
         override
         returns (uint256 loanId, uint256 collateralCount)
     {
-        // Do not let reward-token callbacks mutate claim accounting during an inbound transfer.
-        _requireNotAcceptingToken();
-
-        // Revert if no token IDs are provided.
-        if (tokenIds.length == 0) revert JBDistributor_EmptyTokenIds({tokenIdCount: tokenIds.length});
-
-        // One distributor-held Revnet loan tracks one token ID so one repayment restores one vesting schedule.
-        if (tokenIds.length != 1) revert JBDistributor_UnexpectedTokenCount({tokenCount: tokenIds.length});
-
-        // One loan collateralizes one revnet reward token.
-        if (tokens.length != 1) revert JBDistributor_UnexpectedTokenCount({tokenCount: tokens.length});
-
-        // Zero vesting means rewards are immediately collectible, so there is no locked position to borrow against.
-        if (VESTING_ROUNDS == 0) revert JBDistributor_VestingLoansDisabled();
-
-        // Revnet loan-backed collection is disabled unless a trusted loans contract was set at deployment.
-        if (address(REV_LOANS) == address(0)) revert JBDistributor_RevnetLoansNotConfigured();
-
-        // Make sure that all tokens can be claimed by this sender.
-        _requireCanClaimTokenIds({hook: hook, tokenIds: tokenIds});
-
-        // Bundle the remaining borrow parameters to keep the loan workflow readable and stack-safe.
-        JBBorrowContext memory ctx = JBBorrowContext({
+        (loanId, collateralCount) = _borrowAgainstVestingFor({
             hook: hook,
-            tokenId: tokenIds[0],
-            token: tokens[0],
+            groupId: 0,
+            tokenIds: tokenIds,
+            tokens: tokens,
             sourceToken: sourceToken,
             minBorrowAmount: minBorrowAmount,
             prepaidFeePercent: prepaidFeePercent,
-            beneficiary: beneficiary,
-            revnetId: _revnetIdOf(tokens[0])
+            beneficiary: beneficiary
         });
-
-        // Open and track the distributor-owned loan.
-        (loanId, collateralCount) = _borrowAgainstVesting({ctx: ctx, tokenIds: tokenIds, tokens: tokens});
     }
 
     /// @notice Repay a distributor-held Revnet loan and restore its collateral to the original vesting schedule.
@@ -767,15 +551,210 @@ abstract contract JBDistributor is IJBDistributor {
 
     /// @notice Claim all past reward rounds for the given token IDs and reward tokens into fresh vesting entries.
     /// @param hook The hook whose stakers are claiming.
+    /// @param groupId The reward group being claimed (0 = the default group).
     /// @param tokenIds The token IDs to claim for.
     /// @param tokens The reward tokens to claim.
-    function _claimPastRewards(address hook, uint256[] calldata tokenIds, IERC20[] calldata tokens) internal virtual;
+    function _claimPastRewards(
+        address hook,
+        uint256 groupId,
+        uint256[] calldata tokenIds,
+        IERC20[] calldata tokens
+    )
+        internal
+        virtual;
 
     /// @notice Revert unless the caller is authorized to claim each token ID.
     /// @param hook The hook whose token IDs are being checked.
     /// @param tokenIds The token IDs to check.
     function _requireCanClaimTokenIds(address hook, uint256[] calldata tokenIds) internal view virtual;
 
+    /// @notice Shared begin-vesting logic across reward groups.
+    /// @param hook The hook whose stakers are vesting.
+    /// @param groupId The reward group (0 = the default group).
+    /// @param tokenIds The staker token IDs to claim rewards for.
+    /// @param tokens The reward tokens to begin vesting.
+    function _beginVesting(
+        address hook,
+        uint256 groupId,
+        uint256[] calldata tokenIds,
+        IERC20[] calldata tokens
+    )
+        internal
+    {
+        // Reward accounting cannot change while an ERC-20 `transferFrom` is in progress.
+        _requireNotAcceptingToken();
+
+        // Revert if no token IDs are provided.
+        if (tokenIds.length == 0) revert JBDistributor_EmptyTokenIds({tokenIdCount: tokenIds.length});
+
+        // Only the entity authorized for these token IDs may start their vesting clock.
+        _requireCanClaimTokenIds({hook: hook, tokenIds: tokenIds});
+
+        // Materialize all unclaimed historical reward rounds into fresh vesting entries that start now.
+        _claimPastRewards({hook: hook, groupId: groupId, tokenIds: tokenIds, tokens: tokens});
+    }
+
+    /// @notice Shared begin-vesting-then-collect logic across reward groups.
+    /// @param hook The hook whose stakers are collecting.
+    /// @param groupId The reward group (0 = the default group).
+    /// @param tokenIds The token IDs to collect for.
+    /// @param tokens The reward tokens to collect.
+    /// @param beneficiary The recipient of the collected tokens.
+    function _collectVestedRewards(
+        address hook,
+        uint256 groupId,
+        uint256[] calldata tokenIds,
+        IERC20[] calldata tokens,
+        address beneficiary
+    )
+        internal
+    {
+        // Collections transfer reward tokens out; block them mid inbound transfer.
+        _requireNotAcceptingToken();
+
+        // Revert if no token IDs are provided.
+        if (tokenIds.length == 0) revert JBDistributor_EmptyTokenIds({tokenIdCount: tokenIds.length});
+
+        // Only the entity authorized for these token IDs may materialize and collect their rewards.
+        _requireCanClaimTokenIds({hook: hook, tokenIds: tokenIds});
+
+        // Before collecting, bring the token IDs current by starting vesting for any past reward rounds.
+        _claimPastRewards({hook: hook, groupId: groupId, tokenIds: tokenIds, tokens: tokens});
+
+        // Release whatever portion of existing vesting entries has unlocked by this round.
+        _unlockRewards({
+            hook: hook, groupId: groupId, tokenIds: tokenIds, tokens: tokens, beneficiary: beneficiary, ownerClaim: true
+        });
+    }
+
+    /// @notice Shared forfeiture-release logic across reward groups.
+    /// @param hook The hook whose tokens were burned.
+    /// @param groupId The reward group (0 = the default group).
+    /// @param tokenIds The IDs of the burned tokens.
+    /// @param tokens The reward tokens to recycle.
+    /// @param beneficiary Unused for forfeiture. Kept for interface compatibility.
+    function _releaseForfeitedRewards(
+        address hook,
+        uint256 groupId,
+        uint256[] calldata tokenIds,
+        IERC20[] calldata tokens,
+        address beneficiary
+    )
+        internal
+    {
+        // Do not let reward-token callbacks mutate vesting state during inbound balance-delta accounting.
+        _requireNotAcceptingToken();
+
+        // Make sure that all staker token IDs are burned.
+        for (uint256 i; i < tokenIds.length;) {
+            if (!_tokenBurned({hook: hook, tokenId: tokenIds[i]})) {
+                revert JBDistributor_NoAccess({hook: hook, tokenId: tokenIds[i], account: msg.sender});
+            }
+            unchecked {
+                ++i;
+            }
+        }
+
+        // Unlock the rewards and recycle the forfeited amount.
+        _unlockRewards({
+            hook: hook,
+            groupId: groupId,
+            tokenIds: tokenIds,
+            tokens: tokens,
+            beneficiary: beneficiary,
+            ownerClaim: false
+        });
+    }
+
+    /// @notice Shared expired-reward recycling logic across reward groups.
+    /// @param hook The hook whose expired rewards should be recycled.
+    /// @param groupId The reward group (0 = the default 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 groupId,
+        IERC20 token,
+        uint256[] calldata rounds
+    )
+        internal
+        returns (uint256 amount)
+    {
+        // Do not let reward-token callbacks recycle inventory during an inbound balance-delta measurement.
+        _requireNotAcceptingToken();
+
+        // Process every requested round independently so callers can batch keeper work.
+        for (uint256 i; i < rounds.length;) {
+            amount += _recycleExpiredRewardRound({hook: hook, groupId: groupId, token: token, round: rounds[i]});
+            unchecked {
+                ++i;
+            }
+        }
+    }
+
+    /// @notice Shared borrow-against-vesting logic across reward groups.
+    /// @param hook The hook whose staker is borrowing against vesting rewards.
+    /// @param groupId The reward group (0 = the default group).
+    /// @param tokenIds The single 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 _borrowAgainstVestingFor(
+        address hook,
+        uint256 groupId,
+        uint256[] calldata tokenIds,
+        IERC20[] calldata tokens,
+        address sourceToken,
+        uint256 minBorrowAmount,
+        uint256 prepaidFeePercent,
+        address payable beneficiary
+    )
+        internal
+        returns (uint256 loanId, uint256 collateralCount)
+    {
+        // Do not let reward-token callbacks mutate claim accounting during an inbound transfer.
+        _requireNotAcceptingToken();
+
+        // Revert if no token IDs are provided.
+        if (tokenIds.length == 0) revert JBDistributor_EmptyTokenIds({tokenIdCount: tokenIds.length});
+
+        // One distributor-held Revnet loan tracks one token ID so one repayment restores one vesting schedule.
+        if (tokenIds.length != 1) revert JBDistributor_UnexpectedTokenCount({tokenCount: tokenIds.length});
+
+        // One loan collateralizes one revnet reward token.
+        if (tokens.length != 1) revert JBDistributor_UnexpectedTokenCount({tokenCount: tokens.length});
+
+        // Zero vesting means rewards are immediately collectible, so there is no locked position to borrow against.
+        if (VESTING_ROUNDS == 0) revert JBDistributor_VestingLoansDisabled();
+
+        // Revnet loan-backed collection is disabled unless a trusted loans contract was set at deployment.
+        if (address(REV_LOANS) == address(0)) revert JBDistributor_RevnetLoansNotConfigured();
+
+        // Make sure that all tokens can be claimed by this sender.
+        _requireCanClaimTokenIds({hook: hook, tokenIds: tokenIds});
+
+        // Bundle the remaining borrow parameters to keep the loan workflow readable and stack-safe.
+        JBBorrowContext memory ctx = JBBorrowContext({
+            hook: hook,
+            groupId: groupId,
+            tokenId: tokenIds[0],
+            token: tokens[0],
+            sourceToken: sourceToken,
+            minBorrowAmount: minBorrowAmount,
+            prepaidFeePercent: prepaidFeePercent,
+            beneficiary: beneficiary,
+            revnetId: _revnetIdOf(tokens[0])
+        });
+
+        // Open and track the distributor-owned loan.
+        (loanId, collateralCount) = _borrowAgainstVesting({ctx: ctx, tokenIds: tokenIds, tokens: tokens});
+    }
+
     /// @notice Open and track a distributor-held Revnet loan against one vesting position.
     /// @param ctx The borrow context.
     /// @param tokenIds The single token ID being collateralized.
@@ -791,7 +770,7 @@ abstract contract JBDistributor is IJBDistributor {
         returns (uint256 loanId, uint256 collateralCount)
     {
         // One vesting position cannot be collateralized by two outstanding loans.
-        uint256 activeLoanId = activeVestingLoanIdOf[ctx.hook][ctx.tokenId][ctx.token];
+        uint256 activeLoanId = activeVestingLoanIdOf[ctx.hook][ctx.groupId][ctx.tokenId][ctx.token];
         if (activeLoanId != 0) {
             revert JBDistributor_VestingLoanOutstanding({
                 hook: ctx.hook, tokenId: ctx.tokenId, token: address(ctx.token), loanId: activeLoanId
@@ -799,13 +778,14 @@ abstract contract JBDistributor is IJBDistributor {
         }
 
         // Bring the claimant current before measuring collateral.
-        _claimPastRewards({hook: ctx.hook, tokenIds: tokenIds, tokens: tokens});
+        _claimPastRewards({hook: ctx.hook, groupId: ctx.groupId, tokenIds: tokenIds, tokens: tokens});
 
         // Use the remaining uncollected vesting amount as collateral without advancing the vesting schedule.
-        collateralCount = _unclaimedVestingAmountOf({hook: ctx.hook, tokenId: ctx.tokenId, token: ctx.token});
+        collateralCount =
+            _unclaimedVestingAmountOf({hook: ctx.hook, groupId: ctx.groupId, tokenId: ctx.tokenId, token: ctx.token});
 
         // Remember the vesting-entry boundary so liquidation write-off cannot consume later rewards.
-        uint48 vestingDataCount = _toUint48(vestingDataOf[ctx.hook][ctx.tokenId][ctx.token].length);
+        uint48 vestingDataCount = _toUint48(vestingDataOf[ctx.hook][ctx.groupId][ctx.tokenId][ctx.token].length);
 
         // A zero-collateral loan would revert in Revnet, but this local error explains why.
         if (collateralCount == 0) {
@@ -818,7 +798,7 @@ abstract contract JBDistributor is IJBDistributor {
         totalLoanedVestingAmountOf[ctx.hook][ctx.token] += collateralCount;
 
         // Block same-position reentrancy before the loan contract burns collateral and returns the real loan ID.
-        activeVestingLoanIdOf[ctx.hook][ctx.tokenId][ctx.token] = _PENDING_VESTING_LOAN_ID;
+        activeVestingLoanIdOf[ctx.hook][ctx.groupId][ctx.tokenId][ctx.token] = _PENDING_VESTING_LOAN_ID;
 
         // Open the Revnet loan with this distributor as the holder whose tokens are burned as collateral.
         loanId = _openVestingLoan({ctx: ctx, collateralCount: collateralCount});
@@ -827,9 +807,10 @@ abstract contract JBDistributor is IJBDistributor {
         }
 
         // Track the distributor-held loan so repayment can restore the same vesting position.
-        activeVestingLoanIdOf[ctx.hook][ctx.tokenId][ctx.token] = loanId;
+        activeVestingLoanIdOf[ctx.hook][ctx.groupId][ctx.tokenId][ctx.token] = loanId;
         _vestingLoanOf[loanId] = JBVestingLoan({
             hook: ctx.hook,
+            groupId: ctx.groupId,
             tokenId: ctx.tokenId,
             token: ctx.token,
             vestingDataCount: vestingDataCount,
@@ -979,7 +960,7 @@ abstract contract JBDistributor is IJBDistributor {
         totalLoanedVestingAmountOf[vestingLoan.hook][vestingLoan.token] -= vestingLoan.collateralCount;
 
         // Clear the lock that prevented this position from being collected while collateralized.
-        delete activeVestingLoanIdOf[vestingLoan.hook][vestingLoan.tokenId][vestingLoan.token];
+        delete activeVestingLoanIdOf[vestingLoan.hook][vestingLoan.groupId][vestingLoan.tokenId][vestingLoan.token];
         delete _vestingLoanOf[loanId];
 
         // Return any excess reward tokens created during source-fee payment to the repayer.
@@ -1013,10 +994,12 @@ abstract contract JBDistributor is IJBDistributor {
         collateralCount = vestingLoan.collateralCount;
 
         // Load the vesting entries for the token ID whose rewards were collateralized.
-        JBVestingData[] storage vestings = vestingDataOf[vestingLoan.hook][vestingLoan.tokenId][vestingLoan.token];
+        JBVestingData[] storage vestings =
+            vestingDataOf[vestingLoan.hook][vestingLoan.groupId][vestingLoan.tokenId][vestingLoan.token];
 
         // Start at the first unexhausted vesting entry.
-        uint256 vestedIndex = latestVestedIndexOf[vestingLoan.hook][vestingLoan.tokenId][vestingLoan.token];
+        uint256 vestedIndex =
+            latestVestedIndexOf[vestingLoan.hook][vestingLoan.groupId][vestingLoan.tokenId][vestingLoan.token];
 
         // Stop at the boundary recorded when the loan opened, preserving newer vesting entries.
         uint256 vestingDataCount = vestingLoan.vestingDataCount;
@@ -1032,7 +1015,7 @@ abstract contract JBDistributor is IJBDistributor {
         }
 
         // Skip over the written-off vesting entries without ever moving the cursor backwards.
-        latestVestedIndexOf[vestingLoan.hook][vestingLoan.tokenId][vestingLoan.token] = vestedIndex;
+        latestVestedIndexOf[vestingLoan.hook][vestingLoan.groupId][vestingLoan.tokenId][vestingLoan.token] = vestedIndex;
 
         // Remove the liquidated collateral from the amount still considered vesting.
         totalVestingAmountOf[vestingLoan.hook][vestingLoan.token] -= collateralCount;
@@ -1041,7 +1024,7 @@ abstract contract JBDistributor is IJBDistributor {
         totalLoanedVestingAmountOf[vestingLoan.hook][vestingLoan.token] -= collateralCount;
 
         // Clear the active loan lock for this token ID and reward token.
-        delete activeVestingLoanIdOf[vestingLoan.hook][vestingLoan.tokenId][vestingLoan.token];
+        delete activeVestingLoanIdOf[vestingLoan.hook][vestingLoan.groupId][vestingLoan.tokenId][vestingLoan.token];
 
         // Clear the loan metadata so it cannot be written off or repaid again.
         delete _vestingLoanOf[loanId];
@@ -1092,9 +1075,10 @@ abstract contract JBDistributor is IJBDistributor {
 
     /// @notice Accept funds and assign them to this round's reward ledger.
     /// @param hook The stake source whose stakers receive the rewards.
+    /// @param groupId The reward group being funded (0 = the default group).
     /// @param token The reward token being funded.
     /// @param amount The nominal amount to fund.
-    function _fund(address hook, IERC20 token, uint256 amount) internal {
+    function _fund(address hook, uint256 groupId, IERC20 token, uint256 amount) internal {
         // Native funding is measured by msg.value, not the caller-provided amount.
         if (address(token) == JBConstants.NATIVE_TOKEN) {
             amount = msg.value;
@@ -1109,38 +1093,41 @@ abstract contract JBDistributor is IJBDistributor {
         }
 
         // Store the accepted amount in this round's historical reward ledger.
-        _recordRewardFunding({hook: hook, token: token, amount: amount});
+        _recordRewardFunding({hook: hook, groupId: groupId, token: token, amount: amount});
     }
 
     /// @notice Record accepted funding as the current round's reward pot.
     /// @param hook The stake source whose stakers receive the rewards.
+    /// @param groupId The reward group (0 = the default group).
     /// @param token The reward token.
     /// @param amount The accepted funding amount.
-    function _recordRewardFunding(address hook, IERC20 token, uint256 amount) internal {
+    function _recordRewardFunding(address hook, uint256 groupId, IERC20 token, uint256 amount) internal {
         // Zero-value transfers do not create reward rounds or alter tracked balances.
         if (amount == 0) return;
 
         // Add the accepted amount to the current reward ledger.
-        _recordRewardRound({hook: hook, token: token, amount: amount});
+        _recordRewardRound({hook: hook, groupId: groupId, token: token, amount: amount});
 
-        // Keep the base distributor's balance accounting in sync for collection and conservation checks.
+        // Keep the base distributor's balance accounting in sync for collection and conservation checks. Balances
+        // are tracked per (hook, token) across all groups because they share one token custody pool.
         _balanceOf[hook][token] += amount;
         _accountedBalanceOf[token] += amount;
     }
 
     /// @notice Record rewards as the current round's claimable historical reward pot.
     /// @param hook The stake source whose stakers receive the rewards.
+    /// @param groupId The reward group (0 = the default group).
     /// @param token The reward token.
     /// @param amount The amount to add to the current reward round.
-    function _recordRewardRound(address hook, IERC20 token, uint256 amount) internal {
+    function _recordRewardRound(address hook, uint256 groupId, IERC20 token, uint256 amount) internal {
         // Zero-value rewards do not create reward rounds.
         if (amount == 0) return;
 
         // Rewards belong to the round in progress when they enter the ledger.
         uint256 round = currentRound();
 
-        // Load the current round's ledger entry for this hook and reward token.
-        JBRewardRoundData storage rewardRound = rewardRoundOf[hook][token][round];
+        // Load the current round's ledger entry for this hook, group, and reward token.
+        JBRewardRoundData storage rewardRound = rewardRoundOf[hook][groupId][token][round];
 
         // Every reward round in this contract uses the same immutable claim duration.
         uint48 claimDeadline = _claimDeadlineFor(round);
@@ -1156,8 +1143,8 @@ abstract contract JBDistributor is IJBDistributor {
             // Store the packed claim deadline fixed for this distributor.
             rewardRound.claimDeadline = claimDeadline;
 
-            // Store the packed total stake that shares this round's reward pot.
-            rewardRound.totalStake = _toUint208(_totalStake({hook: hook, blockNumber: snapshotBlock}));
+            // Store the packed total stake that shares this group's round reward pot.
+            rewardRound.totalStake = _toUint208(_totalStake({hook: hook, groupId: groupId, blockNumber: snapshotBlock}));
         }
 
         // Multiple additions in the same round share the same snapshot and reward pot.
@@ -1166,11 +1153,13 @@ abstract contract JBDistributor is IJBDistributor {
 
     /// @notice Recycle one expired reward round's unclaimed inventory into the current reward round.
     /// @param hook The hook whose expired rewards should be recycled.
+    /// @param groupId The reward group (0 = the default group).
     /// @param token The reward token to recycle.
     /// @param round The reward round to recycle.
     /// @return recycleAmount The amount recycled.
     function _recycleExpiredRewardRound(
         address hook,
+        uint256 groupId,
         IERC20 token,
         uint256 round
     )
@@ -1178,7 +1167,7 @@ abstract contract JBDistributor is IJBDistributor {
         returns (uint256 recycleAmount)
     {
         // Load the reward round once so expiry, claimed amount, and funded amount stay in sync.
-        JBRewardRoundData storage rewardRound = rewardRoundOf[hook][token][round];
+        JBRewardRoundData storage rewardRound = rewardRoundOf[hook][groupId][token][round];
 
         // Ignore rounds that either never expire or have not reached their deadline yet.
         if (!_rewardRoundExpired(rewardRound)) return 0;
@@ -1194,7 +1183,7 @@ abstract contract JBDistributor is IJBDistributor {
 
         // Keep the inventory in the distributor and give the current staker set a new claimable round.
         uint256 recycledToRound = currentRound();
-        _recordRewardRound({hook: hook, token: token, amount: recycleAmount});
+        _recordRewardRound({hook: hook, groupId: groupId, token: token, amount: recycleAmount});
 
         // Surface the permissionless recycle for off-chain accounting.
         emit ExpiredRewardsRecycled({
@@ -1261,41 +1250,6 @@ abstract contract JBDistributor is IJBDistributor {
         }
     }
 
-    /// @notice Takes a snapshot of the token balance and vesting amount for the current round.
-    /// @param hook The hook to take the snapshot for.
-    /// @param token The token address to take a snapshot of.
-    /// @return snapshot The snapshot data.
-    function _takeSnapshotOf(address hook, IERC20 token) internal returns (JBTokenSnapshotData memory snapshot) {
-        // Keep a reference to the current round.
-        uint256 round = currentRound();
-
-        // If a snapshot was already taken at this round, do not take a new one. The init flag must be used as the
-        // sentinel: a zero balance is a valid snapshot value (round started with no funded balance), not a signal
-        // to re-snapshot. Re-snapshotting would let mid-round deposits leak into the current round's allocation.
-        if (_snapshotInitializedFor[hook][token][round]) {
-            return _snapshotAtRoundOf[hook][token][round];
-        }
-
-        // Exclude collateralized vesting inventory because those tokens have been burned into distributor-held loans.
-        uint256 vestingAmount = totalVestingAmountOf[hook][token] - totalLoanedVestingAmountOf[hook][token];
-
-        // Take a snapshot using the hook's tracked balance.
-        snapshot = JBTokenSnapshotData({balance: _balanceOf[hook][token], vestingAmount: vestingAmount});
-
-        // Store the snapshot and mark it initialized.
-        _snapshotAtRoundOf[hook][token][round] = snapshot;
-        _snapshotInitializedFor[hook][token][round] = true;
-
-        emit SnapshotCreated({
-            hook: hook,
-            round: round,
-            token: token,
-            balance: snapshot.balance,
-            vestingAmount: snapshot.vestingAmount,
-            caller: msg.sender
-        });
-    }
-
     /// @notice The deadline for a reward round using this distributor's immutable claim duration.
     /// @param round The reward round.
     /// @return claimDeadline The deadline timestamp. Zero means no expiration.
@@ -1321,12 +1275,14 @@ abstract contract JBDistributor is IJBDistributor {
 
     /// @notice Unlocks rewards for the given token IDs and tokens, either for collection or forfeiture.
     /// @param hook The hook the tokens belong to.
+    /// @param groupId The reward group (0 = the default group).
     /// @param tokenIds The IDs of the tokens to unlock rewards for.
     /// @param tokens The addresses of the tokens to unlock.
     /// @param beneficiary The recipient of the unlocked tokens.
     /// @param ownerClaim Whether this is a claim by the owner (true) or a forfeiture release (false).
     function _unlockRewards(
         address hook,
+        uint256 groupId,
         uint256[] calldata tokenIds,
         IERC20[] calldata tokens,
         address beneficiary,
@@ -1341,7 +1297,8 @@ abstract contract JBDistributor is IJBDistributor {
             IERC20 token = tokens[i];
 
             // Process all token IDs for this reward token.
-            uint256 totalTokenAmount = _unlockTokenIds({hook: hook, tokenIds: tokenIds, token: token, round: round});
+            uint256 totalTokenAmount =
+                _unlockTokenIds({hook: hook, groupId: groupId, tokenIds: tokenIds, token: token, round: round});
 
             // Perform the transfer.
             if (totalTokenAmount != 0) {
@@ -1368,7 +1325,7 @@ abstract contract JBDistributor is IJBDistributor {
                     }
                 } else {
                     // If forfeiture: keep inventory in the distributor and give the current staker set a fresh round.
-                    _recordRewardRound({hook: hook, token: token, amount: totalTokenAmount});
+                    _recordRewardRound({hook: hook, groupId: groupId, token: token, amount: totalTokenAmount});
                     emit ForfeitedRewardsRecycled({
                         hook: hook, round: round, token: token, amount: totalTokenAmount, caller: msg.sender
                     });
@@ -1383,12 +1340,14 @@ abstract contract JBDistributor is IJBDistributor {
 
     /// @notice Unlocks rewards for a set of token IDs for a single reward token.
     /// @param hook The hook the tokens belong to.
+    /// @param groupId The reward group (0 = the default group).
     /// @param tokenIds The IDs of the tokens to unlock rewards for.
     /// @param token The reward token to unlock.
     /// @param round The current round.
     /// @return totalTokenAmount The total amount of reward tokens unlocked.
     function _unlockTokenIds(
         address hook,
+        uint256 groupId,
         uint256[] calldata tokenIds,
         IERC20 token,
         uint256 round
@@ -1400,13 +1359,13 @@ abstract contract JBDistributor is IJBDistributor {
             uint256 tokenId = tokenIds[j];
 
             // Loan collateral stays locked until repayment restores it to this distributor.
-            _requireNoActiveVestingLoan({hook: hook, tokenId: tokenId, token: token});
+            _requireNoActiveVestingLoan({hook: hook, groupId: groupId, tokenId: tokenId, token: token});
 
             // Keep a reference to the latest vested index.
-            uint256 vestedIndex = latestVestedIndexOf[hook][tokenId][token];
+            uint256 vestedIndex = latestVestedIndexOf[hook][groupId][tokenId][token];
 
             // Keep a reference to the vesting data array.
-            JBVestingData[] storage vestings = vestingDataOf[hook][tokenId][token];
+            JBVestingData[] storage vestings = vestingDataOf[hook][groupId][tokenId][token];
             uint256 numberOfVestingRounds = vestings.length;
 
             // Keep a reference to a vested index that will be incremented.
@@ -1441,6 +1400,7 @@ abstract contract JBDistributor is IJBDistributor {
                     emit Collected({
                         hook: hook,
                         tokenId: tokenId,
+                        groupId: groupId,
                         token: token,
                         amount: claimAmount,
                         vestingReleaseRound: vesting.releaseRound,
@@ -1462,7 +1422,7 @@ abstract contract JBDistributor is IJBDistributor {
                 }
             }
 
-            latestVestedIndexOf[hook][tokenId][token] = newLatestVestedIndex;
+            latestVestedIndexOf[hook][groupId][tokenId][token] = newLatestVestedIndex;
 
             unchecked {
                 ++j;
@@ -1470,93 +1430,77 @@ abstract contract JBDistributor is IJBDistributor {
         }
     }
 
-    /// @notice Vests each token ID for a given reward token and returns the total amount vested.
-    /// @dev Silently skips already-vested tokenIds instead of reverting, to support auto-vest.
-    /// @param hook The hook whose stakers are vesting.
-    /// @param tokenIds The IDs to claim rewards for.
-    /// @param token The reward token.
-    /// @param distributable The distributable amount for this round.
-    /// @param totalStakeAmount The total stake amount.
-    /// @param vestingReleaseRound The round at which vesting will be released.
-    /// @return totalVestingAmount The total amount that began vesting.
-    function _vestTokenIds(
+    //*********************************************************************//
+    // ----------------------- internal views ---------------------------- //
+    //*********************************************************************//
+
+    /// @notice The collectable (unlocked, uncollected) amount for a token ID in a specific reward group.
+    /// @param hook The hook the tokenId belongs to.
+    /// @param groupId The reward group (0 = the default group).
+    /// @param tokenId The ID of the staker token to calculate for.
+    /// @param token The reward token to check.
+    /// @return tokenAmount The amount of tokens that can be collected right now.
+    function _collectableFor(
         address hook,
-        uint256[] calldata tokenIds,
-        IERC20 token,
-        uint256 distributable,
-        uint256 totalStakeAmount,
-        uint256 vestingReleaseRound
+        uint256 groupId,
+        uint256 tokenId,
+        IERC20 token
     )
         internal
-        virtual
-        returns (uint256 totalVestingAmount)
+        view
+        returns (uint256 tokenAmount)
     {
-        for (uint256 j; j < tokenIds.length;) {
-            uint256 tokenId = tokenIds[j];
+        // A loan keeps this token ID's vesting rewards in collateral custody until the loan is repaid.
+        if (activeVestingLoanIdOf[hook][groupId][tokenId][token] != 0) return 0;
 
-            // Skip burned tokens — they are excluded from _totalStake, so including them would overbook vesting.
-            if (_tokenBurned({hook: hook, tokenId: tokenId})) {
-                unchecked {
-                    ++j;
-                }
-                continue;
-            }
+        // The round that we are in right now.
+        uint256 round = currentRound();
 
-            // Keep a reference to the vesting data for this hook/tokenId/token.
-            JBVestingData[] storage vestings = vestingDataOf[hook][tokenId][token];
+        // Keep a reference to the latest vested index.
+        uint256 vestedIndex = latestVestedIndexOf[hook][groupId][tokenId][token];
 
-            // Skip if this token has already been vested for this round (same releaseRound).
-            uint256 numVesting = vestings.length;
-            if (numVesting != 0 && vestings[numVesting - 1].releaseRound == vestingReleaseRound) {
-                unchecked {
-                    ++j;
-                }
-                continue;
-            }
+        // Keep a reference to the vesting data array.
+        JBVestingData[] storage vestings = vestingDataOf[hook][groupId][tokenId][token];
+        uint256 numberOfVestingRounds = vestings.length;
 
-            // Keep a reference to the amount of tokens being claimed.
-            uint256 tokenAmount = mulDiv({
-                x: distributable, y: _tokenStake({hook: hook, tokenId: tokenId}), denominator: totalStakeAmount
-            });
+        while (vestedIndex < numberOfVestingRounds) {
+            uint256 lockedShare;
 
-            // Skip zero-amount entries to prevent stalling latestVestedIndexOf advancement.
-            if (tokenAmount == 0) {
-                unchecked {
-                    ++j;
-                }
-                continue;
-            }
+            // Keep a reference to the vested data being iterated on.
+            JBVestingData memory vesting = vestings[vestedIndex];
 
-            // Add to the list of vesting data.
-            vestings.push(JBVestingData({releaseRound: vestingReleaseRound, amount: tokenAmount, shareClaimed: 0}));
+            lockedShare = JBVestingMath.lockedShareOf({
+                releaseRound: vesting.releaseRound,
+                currentRound: round,
+                vestingRounds: VESTING_ROUNDS,
+                maxShare: MAX_SHARE
+            });
 
-            emit Claimed({
-                hook: hook,
-                tokenId: tokenId,
-                token: token,
-                amount: tokenAmount,
-                vestingReleaseRound: vestingReleaseRound,
-                caller: msg.sender
+            // Calculate the newly unlocked amount from cumulative shares rather than the incremental share delta.
+            // Incremental floor rounding can otherwise underpay partial collections and leave dust stranded.
+            (uint256 claimAmount,) = JBVestingMath.newlyClaimableAmountOf({
+                amount: vesting.amount,
+                shareClaimed: vesting.shareClaimed,
+                lockedShare: lockedShare,
+                maxShare: MAX_SHARE
             });
+            tokenAmount += claimAmount;
 
             unchecked {
-                totalVestingAmount += tokenAmount;
-                ++j;
+                ++vestedIndex;
             }
         }
     }
 
-    //*********************************************************************//
-    // ----------------------- internal views ---------------------------- //
-    //*********************************************************************//
-
     /// @notice The remaining uncollected vesting amount for one token ID and reward token.
     /// @param hook The hook the token ID belongs to.
+    /// @param groupId The reward group (0 = the default group).
     /// @param tokenId The token ID to check.
     /// @param token The reward token to check.
     /// @return tokenAmount The amount still locked or unlocked-but-uncollected.
     function _unclaimedVestingAmountOf(
         address hook,
+        uint256 groupId,
         uint256 tokenId,
         IERC20 token
     )
@@ -1565,10 +1509,10 @@ abstract contract JBDistributor is IJBDistributor {
         returns (uint256 tokenAmount)
     {
         // Keep a reference to the latest fully vested index.
-        uint256 vestedIndex = latestVestedIndexOf[hook][tokenId][token];
+        uint256 vestedIndex = latestVestedIndexOf[hook][groupId][tokenId][token];
 
         // Keep a reference to the vesting data array.
-        JBVestingData[] storage vestings = vestingDataOf[hook][tokenId][token];
+        JBVestingData[] storage vestings = vestingDataOf[hook][groupId][tokenId][token];
         uint256 numberOfVestingRounds = vestings.length;
 
         while (vestedIndex < numberOfVestingRounds) {
@@ -1604,10 +1548,11 @@ abstract contract JBDistributor is IJBDistributor {
 
     /// @notice Revert if a token ID's vesting rewards are locked in a distributor-owned loan.
     /// @param hook The hook the token ID belongs to.
+    /// @param groupId The reward group (0 = the default group).
     /// @param tokenId The token ID to check.
     /// @param token The reward token to check.
-    function _requireNoActiveVestingLoan(address hook, uint256 tokenId, IERC20 token) internal view {
-        uint256 loanId = activeVestingLoanIdOf[hook][tokenId][token];
+    function _requireNoActiveVestingLoan(address hook, uint256 groupId, uint256 tokenId, IERC20 token) internal view {
+        uint256 loanId = activeVestingLoanIdOf[hook][groupId][tokenId][token];
         if (loanId != 0) {
             revert JBDistributor_VestingLoanOutstanding({
                 hook: hook, tokenId: tokenId, token: address(token), loanId: loanId
@@ -1623,17 +1568,26 @@ abstract contract JBDistributor is IJBDistributor {
     function _tokenBurned(address hook, uint256 tokenId) internal view virtual returns (bool tokenWasBurned);
 
     /// @notice The stake weight of a specific token ID, used to calculate its pro-rata share of distributions.
-    /// For 721 distributors this is the tier's voting units; for token distributors this is delegated voting power.
+    /// @dev Subclasses define how stake is measured.
     /// @param hook The hook the token belongs to.
     /// @param tokenId The ID of the token to get the stake weight of.
     /// @return tokenStakeAmount The stake weight represented by this token ID.
     function _tokenStake(address hook, uint256 tokenId) internal view virtual returns (uint256 tokenStakeAmount);
 
-    /// @notice The total stake across all token IDs at a given block. Used as the denominator when calculating each
-    /// token ID's pro-rata share. For 721 distributors this is `getPastTotalSupply` from the checkpoints module;
-    /// for token distributors this is `getPastTotalSupply` from the IVotes token.
+    /// @notice The total stake sharing a group's round rewards at a given block. Used as the denominator when
+    /// calculating each token ID's pro-rata share.
+    /// @dev Subclasses define how the per-group total stake is measured.
     /// @param hook The hook to get the total stake for.
+    /// @param groupId The reward group (0 = the default group).
     /// @param blockNumber The block number to query (must be strictly in the past).
     /// @return totalStakedAmount The total stake at the given block.
-    function _totalStake(address hook, uint256 blockNumber) internal view virtual returns (uint256 totalStakedAmount);
+    function _totalStake(
+        address hook,
+        uint256 groupId,
+        uint256 blockNumber
+    )
+        internal
+        view
+        virtual
+        returns (uint256 totalStakedAmount);
 }