@bananapus/distributor-v6 0.0.32 → 0.0.34

package/README.md

@@ -2,12 +2,17 @@
 
 `@bananapus/distributor-v6` distributes ERC-20 balances or 721 token inventories to many recipients under round-based vesting rules. It is a payout utility package for Juicebox-adjacent flows, not a protocol accounting layer.
 
-Architecture: [ARCHITECTURE.md](./ARCHITECTURE.md)  
-User journeys: [USER_JOURNEYS.md](./USER_JOURNEYS.md)  
-Skills: [SKILLS.md](./SKILLS.md)  
-Risks: [RISKS.md](./RISKS.md)  
-Administration: [ADMINISTRATION.md](./ADMINISTRATION.md)  
-Audit instructions: [AUDIT_INSTRUCTIONS.md](./AUDIT_INSTRUCTIONS.md)
+## Documentation
+
+- [ARCHITECTURE.md](./ARCHITECTURE.md) — system overview, modules, trust boundaries, and core invariants.
+- [USER_JOURNEYS.md](./USER_JOURNEYS.md) — end-to-end flows for funders and claimants across token and 721 variants.
+- [INVARIANTS.md](./INVARIANTS.md) — per-section invariants for snapshot fairness, vesting math, claim authority, loans, and recycling.
+- [RISKS.md](./RISKS.md) — risk register with priority risks and the minimum invariants to verify.
+- [ADMINISTRATION.md](./ADMINISTRATION.md) — deployment parameters, control posture, and recovery guidance.
+- [SKILLS.md](./SKILLS.md) — quick index for routing tasks into the right sub-document.
+- [STYLE_GUIDE.md](./STYLE_GUIDE.md) — Solidity and repo conventions used across the Juicebox V6 ecosystem.
+- [AUDIT_INSTRUCTIONS.md](./AUDIT_INSTRUCTIONS.md) — audit framing, targets, and suggested hunting grounds.
+- [CHANGELOG.md](./CHANGELOG.md) — release notes and dependency bumps.
 
 ## Overview
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/distributor-v6",
-  "version": "0.0.32",
+  "version": "0.0.34",
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/JB721Distributor.sol

@@ -162,57 +162,10 @@ contract JB721Distributor is JBDistributor, IJB721Distributor {
         }
     }
 
-    /// @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.
-    /// @param tokens The reward tokens to begin vesting.
-    function beginVesting(
-        address hook,
-        uint256[] calldata tokenIds,
-        IERC20[] calldata tokens
-    )
-        external
-        override(JBDistributor, IJBDistributor)
-    {
-        // Do not let reward-token callbacks mutate claim accounting during an inbound transfer.
-        _requireNotAcceptingToken();
-        if (tokenIds.length == 0) revert JBDistributor_EmptyTokenIds({tokenIdCount: tokenIds.length});
-
-        // Only the current NFT owner can start vesting for each token ID.
-        _requireCanClaimTokenIds({hook: hook, tokenIds: tokenIds});
-
-        // Materialize all unclaimed historical rewards into fresh vesting entries that start now.
-        _claimPastRewards({hook: hook, tokenIds: tokenIds, tokens: tokens});
-    }
-
-    /// @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(
-        address hook,
-        uint256[] calldata tokenIds,
-        IERC20[] calldata tokens,
-        address beneficiary
-    )
-        public
-        override(JBDistributor, IJBDistributor)
-    {
-        // Do not let reward-token callbacks mutate claim accounting during an inbound transfer.
-        _requireNotAcceptingToken();
-        if (tokenIds.length == 0) revert JBDistributor_EmptyTokenIds({tokenIdCount: tokenIds.length});
-
-        // Only the current NFT owner can materialize and collect rewards for each token ID.
-        _requireCanClaimTokenIds({hook: hook, tokenIds: tokenIds});
-
-        // Before collecting, bring the token IDs current by starting vesting for any past reward rounds.
-        _claimPastRewards({hook: hook, tokenIds: tokenIds, tokens: tokens});
-
-        // Release whatever portion of existing vesting entries has unlocked by this round.
-        _unlockRewards({hook: hook, tokenIds: tokenIds, tokens: tokens, beneficiary: beneficiary, ownerClaim: true});
-    }
+    // `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.
 
     //*********************************************************************//
     // -------------------------- public views --------------------------- //
@@ -473,75 +426,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 ---------------------------- //
     //*********************************************************************//
@@ -664,132 +548,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
-        });
-    }
 }

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);
 
@@ -202,21 +198,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 +252,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.
@@ -287,55 +270,18 @@ abstract contract JBDistributor is IJBDistributor {
         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.
+        // token could otherwise vest or collect against balances mid-transfer, distorting the credited delta.
         _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;
+        // Only the entity authorized for these token IDs (current NFT owner / encoded staker) may start their
+        // vesting clock — third parties must not start it for them.
+        _requireCanClaimTokenIds({hook: hook, tokenIds: tokenIds});
 
-                ++i;
-            }
-        }
+        // Materialize all unclaimed historical reward rounds into fresh vesting entries that start now.
+        _claimPastRewards({hook: hook, tokenIds: tokenIds, tokens: tokens});
     }
 
     /// @notice Directly fund the distributor for a specific hook by pulling tokens from the caller. An alternative
@@ -506,23 +452,6 @@ abstract contract JBDistributor is IJBDistributor {
         }
     }
 
-    /// @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];
-    }
-
     /// @notice The vesting position collateralized by a Revnet loan.
     /// @param loanId The Revnet loan NFT ID.
     function vestingLoanOf(uint256 loanId) external view override returns (JBVestingLoan memory) {
@@ -548,11 +477,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,62 +495,20 @@ 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.
+        // Collections transfer reward tokens out; block them mid inbound transfer so the outgoing transfer cannot
+        // 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
-                });
+        // Only the entity authorized for these token IDs may materialize and collect their rewards.
+        _requireCanClaimTokenIds({hook: hook, tokenIds: tokenIds});
 
-                unchecked {
-                    totalVestingAmountOf[hook][token] += totalVestingAmount;
-                }
-            }
+        // Before collecting, bring the token IDs current by starting vesting for any past reward rounds.
+        _claimPastRewards({hook: hook, tokenIds: tokenIds, tokens: tokens});
 
-            unchecked {
-                ++i;
-            }
-        }
-
-        // Unlock the rewards and send them to the beneficiary.
+        // Release whatever portion of existing vesting entries has unlocked by this round.
         _unlockRewards({hook: hook, tokenIds: tokenIds, tokens: tokens, beneficiary: beneficiary, ownerClaim: true});
     }
 
@@ -1261,41 +1149,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.
@@ -1470,82 +1323,6 @@ 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(
-        address hook,
-        uint256[] calldata tokenIds,
-        IERC20 token,
-        uint256 distributable,
-        uint256 totalStakeAmount,
-        uint256 vestingReleaseRound
-    )
-        internal
-        virtual
-        returns (uint256 totalVestingAmount)
-    {
-        for (uint256 j; j < tokenIds.length;) {
-            uint256 tokenId = tokenIds[j];
-
-            // Skip burned tokens — they are excluded from _totalStake, so including them would overbook vesting.
-            if (_tokenBurned({hook: hook, tokenId: tokenId})) {
-                unchecked {
-                    ++j;
-                }
-                continue;
-            }
-
-            // Keep a reference to the vesting data for this hook/tokenId/token.
-            JBVestingData[] storage vestings = vestingDataOf[hook][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 amount of tokens being claimed.
-            uint256 tokenAmount = mulDiv({
-                x: distributable, y: _tokenStake({hook: hook, tokenId: tokenId}), denominator: totalStakeAmount
-            });
-
-            // Skip zero-amount entries to prevent stalling latestVestedIndexOf advancement.
-            if (tokenAmount == 0) {
-                unchecked {
-                    ++j;
-                }
-                continue;
-            }
-
-            // Add to the list of vesting data.
-            vestings.push(JBVestingData({releaseRound: vestingReleaseRound, amount: tokenAmount, shareClaimed: 0}));
-
-            emit Claimed({
-                hook: hook,
-                tokenId: tokenId,
-                token: token,
-                amount: tokenAmount,
-                vestingReleaseRound: vestingReleaseRound,
-                caller: msg.sender
-            });
-
-            unchecked {
-                totalVestingAmount += tokenAmount;
-                ++j;
-            }
-        }
-    }
-
     //*********************************************************************//
     // ----------------------- internal views ---------------------------- //
     //*********************************************************************//

package/src/JBTokenDistributor.sol

@@ -144,58 +144,10 @@ contract JBTokenDistributor is JBDistributor, IJBTokenDistributor {
         }
     }
 
-    /// @notice Snapshot this staker's past reward rounds and start vesting them now.
-    /// @dev Unlike the shared distributor flow, token claims are owner-initiated. This prevents third parties from
-    /// starting a staker's vesting clock before the staker actually claims.
-    /// @param hook The IVotes token whose stakers are vesting.
-    /// @param tokenIds The encoded staker addresses to claim for.
-    /// @param tokens The reward tokens to begin vesting.
-    function beginVesting(
-        address hook,
-        uint256[] calldata tokenIds,
-        IERC20[] calldata tokens
-    )
-        external
-        override(JBDistributor, IJBDistributor)
-    {
-        // Do not let reward-token callbacks mutate claim accounting during an inbound transfer.
-        _requireNotAcceptingToken();
-        if (tokenIds.length == 0) revert JBDistributor_EmptyTokenIds({tokenIdCount: tokenIds.length});
-
-        // Token IDs encode staker addresses, so only the encoded staker can start their own vesting clock.
-        _requireCanClaimTokenIds({hook: hook, tokenIds: tokenIds});
-
-        // Materialize all unclaimed historical rewards into fresh vesting entries that start now.
-        _claimPastRewards({hook: hook, tokenIds: tokenIds, tokens: tokens});
-    }
-
-    /// @notice Collect already-vested rewards and first start vesting any unclaimed past reward rounds.
-    /// @param hook The IVotes token whose stakers are collecting.
-    /// @param tokenIds The encoded staker addresses to collect for.
-    /// @param tokens The reward tokens to collect.
-    /// @param beneficiary The recipient of collected vested rewards.
-    function collectVestedRewards(
-        address hook,
-        uint256[] calldata tokenIds,
-        IERC20[] calldata tokens,
-        address beneficiary
-    )
-        public
-        override(JBDistributor, IJBDistributor)
-    {
-        // Do not let reward-token callbacks mutate claim accounting during an inbound transfer.
-        _requireNotAcceptingToken();
-        if (tokenIds.length == 0) revert JBDistributor_EmptyTokenIds({tokenIdCount: tokenIds.length});
-
-        // Only the encoded staker can materialize and collect their token rewards.
-        _requireCanClaimTokenIds({hook: hook, tokenIds: tokenIds});
-
-        // Before collecting, bring the caller current by starting vesting for any past reward rounds.
-        _claimPastRewards({hook: hook, tokenIds: tokenIds, tokens: tokens});
-
-        // Release whatever portion of existing vesting entries has unlocked by this round.
-        _unlockRewards({hook: hook, tokenIds: tokenIds, tokens: tokens, beneficiary: beneficiary, ownerClaim: true});
-    }
+    // `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.
 
     //*********************************************************************//
     // -------------------------- public views --------------------------- //

package/src/interfaces/IJBDistributor.sol

@@ -6,7 +6,6 @@ import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
 import {IREVLoans} from "@rev-net/core-v6/src/interfaces/IREVLoans.sol";
 import {IREVOwner} from "@rev-net/core-v6/src/interfaces/IREVOwner.sol";
 
-import {JBTokenSnapshotData} from "../structs/JBTokenSnapshotData.sol";
 import {JBVestingLoan} from "../structs/JBVestingLoan.sol";
 
 /// @notice Interface for round-based reward distributors with linear vesting. Stakers claim their share of funded
@@ -139,22 +138,6 @@ interface IJBDistributor {
         address caller
     );
 
-    /// @notice Emitted when a snapshot is created for a round.
-    /// @param hook The hook the snapshot is for.
-    /// @param round The round the snapshot was created for.
-    /// @param token The token the snapshot is of.
-    /// @param balance The token balance at the time of the snapshot.
-    /// @param vestingAmount The amount of tokens vesting at the time of the snapshot.
-    /// @param caller The address that triggered the snapshot.
-    event SnapshotCreated(
-        address indexed hook,
-        uint256 indexed round,
-        IERC20 indexed token,
-        uint256 balance,
-        uint256 vestingAmount,
-        address caller
-    );
-
     //*********************************************************************//
     // ----------------------------- views ------------------------------- //
     //*********************************************************************//
@@ -216,19 +199,6 @@ interface IJBDistributor {
     /// @param round The round to get the start timestamp of.
     function roundStartTimestamp(uint256 round) external view returns (uint256);
 
-    /// @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 to check.
-    /// @param round The round to which the data applies.
-    function snapshotAtRoundOf(
-        address hook,
-        IERC20 token,
-        uint256 round
-    )
-        external
-        view
-        returns (JBTokenSnapshotData memory);
-
     /// @notice The amount of a token that is currently vesting for a hook's stakers.
     /// @param hook The hook whose vesting amount to check.
     /// @param token The address of the token that is vesting.

package/src/structs/JBTokenSnapshotData.sol

@@ -1,11 +0,0 @@
-// SPDX-License-Identifier: MIT
-pragma solidity ^0.8.0;
-
-/// @notice A point-in-time snapshot of a reward token's state for a specific hook and round. The distributable
-/// amount for the round is `balance - vestingAmount`.
-/// @custom:member balance The total token balance held for the hook's stakers at snapshot time.
-/// @custom:member vestingAmount The amount currently locked in vesting at snapshot time (not yet distributable).
-struct JBTokenSnapshotData {
-    uint256 balance;
-    uint256 vestingAmount;
-}