@bananapus/distributor-v6 0.0.38 → 0.0.43

package/src/JBTokenDistributor.sol

@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: MIT
 pragma solidity 0.8.28;
 
+import {IJBActiveVotes} from "@bananapus/core-v6/src/interfaces/IJBActiveVotes.sol";
 import {IJBController} from "@bananapus/core-v6/src/interfaces/IJBController.sol";
 import {IJBDirectory} from "@bananapus/core-v6/src/interfaces/IJBDirectory.sol";
 import {IJBSplitHook} from "@bananapus/core-v6/src/interfaces/IJBSplitHook.sol";
@@ -15,27 +16,26 @@ import {IREVLoans} from "@rev-net/core-v6/src/interfaces/IREVLoans.sol";
 import {IREVOwner} from "@rev-net/core-v6/src/interfaces/IREVOwner.sol";
 
 import {JBDistributor} from "./JBDistributor.sol";
-import {IJBDistributor} from "./interfaces/IJBDistributor.sol";
 import {IJBTokenDistributor} from "./interfaces/IJBTokenDistributor.sol";
 import {JBClaimContext} from "./structs/JBClaimContext.sol";
 import {JBRewardRoundData} from "./structs/JBRewardRoundData.sol";
 import {JBVestingData} from "./structs/JBVestingData.sol";
 
-/// @notice A singleton distributor that distributes ERC-20 rewards to IVotes-compatible token stakers with linear
-/// vesting.
+/// @notice A singleton distributor that distributes ERC-20 rewards to IVotes-compatible token holders with delegated
+/// voting power and linear vesting.
 /// @dev Any project can use this distributor by configuring a payout split with
 /// `hook = this contract` and `beneficiary = address(their IVotes token)`.
-/// @dev The stake weight of each staker is their delegated voting power at the funded round's snapshot block.
+/// @dev The stake weight of each holder is their delegated voting power at the funded round's snapshot block.
 /// Holders must delegate (even to themselves) to participate.
-/// @dev Funded rewards are assigned to the funding round. Stakers claim historical rounds lazily; all unclaimed past
-/// rewards begin vesting when the staker claims, not when the rewards were funded.
+/// @dev Funded rewards are assigned to the funding round. Holders claim historical rounds lazily; all unclaimed past
+/// rewards begin vesting when the holder claims, not when the rewards were funded.
 /// @dev Implements `IJBSplitHook` so it can receive tokens directly from Juicebox project payout splits.
 contract JBTokenDistributor is JBDistributor, IJBTokenDistributor {
     //*********************************************************************//
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
-    /// @notice Thrown when a tokenId has non-zero upper bits (above 160), which would alias to the same staker address.
+    /// @notice Thrown when a tokenId has non-zero upper bits (above 160), which would alias to the same holder address.
     error JBTokenDistributor_InvalidTokenId(uint256 tokenId);
 
     /// @notice Thrown when native ETH does not match the split hook context amount.
@@ -52,7 +52,7 @@ contract JBTokenDistributor is JBDistributor, IJBTokenDistributor {
     //*********************************************************************//
 
     /// @notice The JB directory used to verify terminal/controller callers.
-    IJBDirectory public immutable DIRECTORY;
+    IJBDirectory public immutable override DIRECTORY;
 
     //*********************************************************************//
     // --------------------- public stored properties -------------------- //
@@ -71,6 +71,7 @@ contract JBTokenDistributor is JBDistributor, IJBTokenDistributor {
     // -------------------------- constructor ---------------------------- //
     //*********************************************************************//
 
+    /// @notice Initializes the token distributor.
     /// @param directory The JB directory used to verify terminal/controller callers.
     /// @param controller The JB controller used for token registry lookups and revnet loan permissions.
     /// @param revLoans The Revnet loans contract used to borrow against vested revnet rewards.
@@ -93,7 +94,7 @@ contract JBTokenDistributor is JBDistributor, IJBTokenDistributor {
     }
 
     //*********************************************************************//
-    // ---------------------- receive ----------------------------------- //
+    // ------------------------- receive / fallback ---------------------- //
     //*********************************************************************//
 
     /// @notice Allows the contract to receive native ETH (e.g. from payout splits).
@@ -148,9 +149,9 @@ contract JBTokenDistributor is JBDistributor, IJBTokenDistributor {
     }
 
     // `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
+    // same flow (validate -> 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.
+    // `_validateTokenIds` overrides below.
 
     //*********************************************************************//
     // -------------------------- public views --------------------------- //
@@ -170,6 +171,7 @@ contract JBTokenDistributor is JBDistributor, IJBTokenDistributor {
 
     /// @notice Claim all past reward rounds for the given token IDs and reward tokens into fresh vesting entries.
     /// @param hook The IVotes token whose stakers are claiming.
+    /// @param groupId The reward group being claimed.
     /// @param tokenIds The encoded staker addresses to claim for.
     /// @param tokens The reward tokens to claim.
     function _claimPastRewards(
@@ -241,8 +243,9 @@ contract JBTokenDistributor is JBDistributor, IJBTokenDistributor {
         // If the cursor is already past the last completed round, this staker is current.
         if (nextClaimRound > ctx.lastClaimableRound) return 0;
 
-        // Sum this staker's pro-rata share from every unclaimed completed reward round.
-        tokenAmount = _claimRewardsFor({
+        // Sum this staker's pro-rata share from every resolved completed reward round.
+        uint256 newNextClaimRound;
+        (tokenAmount, newNextClaimRound) = _claimRewardsFor({
             hook: ctx.hook,
             groupId: ctx.groupId,
             tokenId: tokenId,
@@ -251,8 +254,10 @@ contract JBTokenDistributor is JBDistributor, IJBTokenDistributor {
             lastRound: ctx.lastClaimableRound
         });
 
-        // Advance the cursor even when the amount is zero, so empty or zero-stake rounds are not rescanned forever.
-        nextClaimRoundOf[ctx.hook][ctx.groupId][tokenId][token] = ctx.lastClaimableRound + 1;
+        // Advance the cursor through resolved rounds.
+        nextClaimRoundOf[ctx.hook][ctx.groupId][tokenId][token] = newNextClaimRound;
+
+        // Avoid writing empty vesting entries when no past round allocates rewards to this staker.
         if (tokenAmount == 0) return 0;
 
         // All accumulated past rewards start a single fresh vesting schedule at the claim round.
@@ -260,6 +265,7 @@ contract JBTokenDistributor is JBDistributor, IJBTokenDistributor {
             JBVestingData({releaseRound: ctx.vestingReleaseRound, amount: tokenAmount, shareClaimed: 0})
         );
 
+        // Emit once per staker and reward token so offchain systems can track the materialized vesting entry.
         emit Claimed({
             hook: ctx.hook,
             tokenId: tokenId,
@@ -271,17 +277,50 @@ contract JBTokenDistributor is JBDistributor, IJBTokenDistributor {
         });
     }
 
-    //*********************************************************************//
-    // ----------------------- internal views ---------------------------- //
-    //*********************************************************************//
+    /// @notice Claim one reward round using its recorded denominator.
+    /// @param hook The IVotes token whose stakers are claiming.
+    /// @param tokenId The encoded staker address.
+    /// @param rewardRound The stored reward-round data.
+    /// @return tokenAmount The amount added to vesting.
+    function _claimRewardRoundFor(
+        address hook,
+        uint256 tokenId,
+        JBRewardRoundData storage rewardRound
+    )
+        internal
+        returns (uint256 tokenAmount)
+    {
+        // Empty-denominator rounds have no pro-rata basis, so they cannot allocate rewards to any staker.
+        if (rewardRound.totalStake == 0) return 0;
+
+        // Use the funding round's snapshot block, not the block at which the staker finally claims.
+        uint256 tokenStakeAmount = _tokenStakeAt({hook: hook, tokenId: tokenId, blockNumber: rewardRound.snapshotBlock});
+
+        // Zero-vote stakers advance their cursor but do not consume reward inventory.
+        if (tokenStakeAmount == 0) return 0;
+
+        // The round's reward pot is split pro-rata across checkpointed voting power.
+        uint256 claimAmount = mulDiv({x: rewardRound.amount, y: tokenStakeAmount, denominator: rewardRound.totalStake});
+
+        // Ignore floor-rounded zero claims to avoid unnecessary storage writes.
+        if (claimAmount == 0) return 0;
+
+        // Track the portion that has started vesting so expiry recycles only the remainder.
+        rewardRound.claimedAmount = _toUint208(uint256(rewardRound.claimedAmount) + claimAmount);
+
+        // Return the exact amount that the caller should append to the staker's vesting entry.
+        tokenAmount = claimAmount;
+    }
 
     /// @notice Claim a staker's unclaimed rewards across a range of historical reward rounds.
     /// @param hook The IVotes token whose stakers are claiming.
+    /// @param groupId The reward group being claimed.
     /// @param tokenId The encoded staker address.
     /// @param token The reward token.
     /// @param firstRound The first reward round to include.
     /// @param lastRound The last reward round to include.
     /// @return tokenAmount The cumulative unclaimed reward amount.
+    /// @return newNextClaimRound The next reward round this staker has not yet resolved.
     function _claimRewardsFor(
         address hook,
         uint256 groupId,
@@ -291,8 +330,10 @@ contract JBTokenDistributor is JBDistributor, IJBTokenDistributor {
         uint256 lastRound
     )
         internal
-        returns (uint256 tokenAmount)
+        returns (uint256 tokenAmount, uint256 newNextClaimRound)
     {
+        newNextClaimRound = lastRound + 1;
+
         // Walk every unclaimed historical round. The caller bounds this to completed rounds only.
         for (uint256 rewardRoundNumber = firstRound; rewardRoundNumber <= lastRound;) {
             // Load this round's reward data for the hook, group, and reward token.
@@ -300,29 +341,12 @@ contract JBTokenDistributor is JBDistributor, IJBTokenDistributor {
 
             // Skip rounds that never received funding.
             if (rewardRound.amount != 0) {
-                // Expired rounds can no longer be claimed as-is; recycle their unclaimed remainder instead.
+                // Expired rounds forfeit unmaterialized inventory into the current active-voter set.
                 if (_rewardRoundExpired(rewardRound)) {
                     _recycleExpiredRewardRound({hook: hook, groupId: groupId, token: token, round: rewardRoundNumber});
-                } else if (rewardRound.totalStake != 0) {
-                    // Use the funding round's snapshot block, not the block at which the staker finally claims.
-                    uint256 tokenStakeAmount =
-                        _tokenStakeAt({hook: hook, tokenId: tokenId, blockNumber: rewardRound.snapshotBlock});
-
-                    // Zero-vote stakers advance their cursor but do not consume reward inventory.
-                    if (tokenStakeAmount != 0) {
-                        // The round's reward pot is split pro-rata across checkpointed voting power.
-                        uint256 claimAmount =
-                            mulDiv({x: rewardRound.amount, y: tokenStakeAmount, denominator: rewardRound.totalStake});
-
-                        // Ignore floor-rounded zero claims to avoid unnecessary storage writes.
-                        if (claimAmount != 0) {
-                            // Track the portion that has started vesting so expiry recycles only the remainder.
-                            rewardRound.claimedAmount = _toUint208(uint256(rewardRound.claimedAmount) + claimAmount);
-
-                            // Add this round's vested amount to the staker's cumulative claim.
-                            tokenAmount += claimAmount;
-                        }
-                    }
+                } else {
+                    // Live rounds can still be materialized by snapshot voters into fresh vesting entries.
+                    tokenAmount += _claimRewardRoundFor({hook: hook, tokenId: tokenId, rewardRound: rewardRound});
                 }
             }
 
@@ -332,18 +356,48 @@ contract JBTokenDistributor is JBDistributor, IJBTokenDistributor {
         }
     }
 
-    /// @notice Check if the account matches the staker address encoded in the tokenId.
-    /// @dev tokenId encodes the staker address as `uint256(uint160(stakerAddress))`.
+    //*********************************************************************//
+    // ----------------------- internal views ---------------------------- //
+    //*********************************************************************//
+
+    /// @notice Check if the account matches the staker address encoded in the token ID.
+    /// @dev The token ID encodes the staker address as `uint256(uint160(stakerAddress))`.
     /// @param hook Unused — access is determined by the tokenId encoding.
     /// @param tokenId The encoded staker address.
     /// @param account The account to check.
     /// @return canClaim True if the account matches the encoded address.
     function _canClaim(address hook, uint256 tokenId, address account) internal pure override returns (bool canClaim) {
+        hook; // Silence unused variable warning.
+        canClaim = _claimBeneficiaryOf({hook: hook, tokenId: tokenId}) == account;
+    }
+
+    /// @notice The encoded staker address that receives permissionless collections.
+    /// @dev Reverts on high-bit aliasing so every token ID maps to exactly one address.
+    /// @param hook Unused — the beneficiary is determined by the token ID encoding.
+    /// @param tokenId The encoded staker address.
+    /// @return beneficiary The staker address encoded in `tokenId`.
+    function _claimBeneficiaryOf(address hook, uint256 tokenId) internal pure override returns (address beneficiary) {
         hook; // Silence unused variable warning.
         if (tokenId >> 160 != 0) revert JBTokenDistributor_InvalidTokenId({tokenId: tokenId});
         // The high bits were checked above, so this cast recovers the encoded address.
         // forge-lint: disable-next-line(unsafe-typecast)
-        canClaim = address(uint160(tokenId)) == account;
+        beneficiary = address(uint160(tokenId));
+    }
+
+    /// @notice Revert unless the caller is authorized to claim each token ID.
+    /// @param hook The IVotes token whose stakers are claiming.
+    /// @param tokenIds The encoded staker addresses to check.
+    function _requireCanClaimTokenIds(address hook, uint256[] calldata tokenIds) internal view override {
+        // Each tokenId is an encoded address, so every requested claim must belong to msg.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;
+            }
+        }
     }
 
     /// @notice IVotes tokens cannot be "burned" in the NFT sense — always returns false.
@@ -359,8 +413,7 @@ contract JBTokenDistributor is JBDistributor, IJBTokenDistributor {
 
     /// @notice The delegated voting power of a staker at the current round's snapshot block.
     /// @dev Uses `IVotes.getPastVotes` for checkpointed lookups. The block number is derived from
-    /// `roundSnapshotBlock[currentRound()]`, which is set on first interaction in a round and
-    /// consistent with the block used for `_totalStake` in `beginVesting` and `collectVestedRewards`.
+    /// `roundSnapshotBlock[currentRound()]`, which is set on first interaction in a round.
     /// @param hook The IVotes-compatible token contract.
     /// @param tokenId The encoded staker address (`uint256(uint160(stakerAddress))`).
     /// @return tokenStakeAmount The delegated voting power at the round's snapshot block.
@@ -369,43 +422,6 @@ contract JBTokenDistributor is JBDistributor, IJBTokenDistributor {
             _tokenStakeAt({hook: hook, tokenId: tokenId, blockNumber: roundSnapshotBlock[currentRound()]});
     }
 
-    /// @notice The total supply of votes at a specific block.
-    /// @dev Uses `IVotes.getPastTotalSupply` for checkpointed lookups. Token distributors have no tier concept, so the
-    /// group only isolates reward storage and does not change the stake denominator.
-    /// @param hook The IVotes-compatible token contract.
-    /// @param groupId The reward group (unused for token distributors — kept for base-hook conformance).
-    /// @param blockNumber The block number to get the total supply at.
-    /// @return totalStakedAmount The total supply of votes at the given block.
-    function _totalStake(
-        address hook,
-        uint256 groupId,
-        uint256 blockNumber
-    )
-        internal
-        view
-        override
-        returns (uint256 totalStakedAmount)
-    {
-        groupId; // Silence unused variable warning — token distributors are group-agnostic in weight.
-        totalStakedAmount = IVotes(hook).getPastTotalSupply(blockNumber);
-    }
-
-    /// @notice Revert unless the caller is authorized to claim each token ID.
-    /// @param hook The IVotes token whose stakers are claiming.
-    /// @param tokenIds The encoded staker addresses to check.
-    function _requireCanClaimTokenIds(address hook, uint256[] calldata tokenIds) internal view override {
-        // Each tokenId is an encoded address, so every requested claim must belong to msg.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;
-            }
-        }
-    }
-
     /// @notice The delegated voting power of a staker at an explicit snapshot block.
     /// @param hook The IVotes-compatible token contract.
     /// @param tokenId The encoded staker address.
@@ -430,4 +446,41 @@ contract JBTokenDistributor is JBDistributor, IJBTokenDistributor {
         // Query the staker's delegated votes at the reward round's fixed snapshot block.
         tokenStakeAmount = IVotes(hook).getPastVotes({account: account, timepoint: blockNumber});
     }
+
+    /// @notice The total stake denominator recorded when a token reward round is first funded.
+    /// @dev Always uses `IJBActiveVotes.getPastTotalActiveVotes`, so undelegated balances such as AMM-held tokens do
+    /// not share rewards. `CLAIM_DURATION` only controls whether unmaterialized allocations can expire.
+    /// @param hook The IVotes-compatible token contract.
+    /// @param groupId The reward group (unused for token distributors — kept for base-hook conformance).
+    /// @param blockNumber The block number to get the active total at.
+    /// @return totalStakedAmount The stake denominator to record for the funded round.
+    function _totalStake(
+        address hook,
+        uint256 groupId,
+        uint256 blockNumber
+    )
+        internal
+        view
+        override
+        returns (uint256 totalStakedAmount)
+    {
+        groupId; // Silence unused variable warning — token distributors are group-agnostic in weight.
+
+        // All token reward rounds split only across units delegated to nonzero delegates at the snapshot block.
+        totalStakedAmount = IJBActiveVotes(hook).getPastTotalActiveVotes(blockNumber);
+    }
+
+    /// @notice Revert unless every token ID can be decoded as a staker address.
+    /// @param hook The IVotes token whose staker slots are being validated.
+    /// @param tokenIds The encoded staker addresses to validate.
+    function _validateTokenIds(address hook, uint256[] calldata tokenIds) internal pure override {
+        // Permissionless helpers can start vesting for any valid encoded staker slot.
+        for (uint256 i; i < tokenIds.length;) {
+            _claimBeneficiaryOf({hook: hook, tokenId: tokenIds[i]});
+
+            unchecked {
+                ++i;
+            }
+        }
+    }
 }

package/src/interfaces/IJB721Distributor.sol

@@ -18,13 +18,15 @@ interface IJB721Distributor is IJBDistributor, IJBSplitHook {
     //*********************************************************************//
 
     /// @notice The JB directory used to verify terminal/controller callers.
-    function DIRECTORY() external view returns (IJBDirectory);
+    /// @return directory The JB directory.
+    function DIRECTORY() external view returns (IJBDirectory directory);
 
     /// @notice Calculate how much of the token has been claimed for the given tokenId in a tier-scoped group.
     /// @param hook The hook the tokenId belongs to.
     /// @param tierIds The strictly-increasing tier set defining the group.
     /// @param tokenId The ID of the token to calculate the token amount for.
     /// @param token The address of the token to check.
+    /// @return tokenAmount The claimed token amount.
     function claimedFor(
         address hook,
         uint256[] calldata tierIds,
@@ -33,14 +35,14 @@ interface IJB721Distributor is IJBDistributor, IJBSplitHook {
     )
         external
         view
-        returns (uint256);
+        returns (uint256 tokenAmount);
 
-    /// @notice Calculate how much of the token is currently ready to be collected for the given tokenId in a
-    /// tier-scoped group.
+    /// @notice Calculate the collectible token amount for a token ID in a tier-scoped group.
     /// @param hook The hook the tokenId belongs to.
     /// @param tierIds The strictly-increasing tier set defining the group.
     /// @param tokenId The ID of the token to calculate the token amount for.
     /// @param token The address of the token to check.
+    /// @return tokenAmount The currently collectable token amount.
     function collectableFor(
         address hook,
         uint256[] calldata tierIds,
@@ -49,7 +51,7 @@ interface IJB721Distributor is IJBDistributor, IJBSplitHook {
     )
         external
         view
-        returns (uint256);
+        returns (uint256 tokenAmount);
 
     /// @notice The tier set that defines a reward group, recorded when the group is first funded.
     /// @dev Empty for the all-tiers group (0).
@@ -63,6 +65,7 @@ interface IJB721Distributor is IJBDistributor, IJBSplitHook {
     //*********************************************************************//
 
     /// @notice Claims tokens and begins vesting from a tier-scoped reward group.
+    /// @dev Permissionless. No reward tokens leave the distributor.
     /// @param hook The hook whose stakers are vesting.
     /// @param tierIds The strictly-increasing tier set defining the group.
     /// @param tokenIds The IDs to claim rewards for.
@@ -99,22 +102,9 @@ interface IJB721Distributor is IJBDistributor, IJBSplitHook {
         external
         returns (uint256 loanId, uint256 collateralCount);
 
-    /// @notice Recycle unclaimed rewards from expired tier-scoped reward rounds into the current reward round.
-    /// @param hook The hook whose expired reward rounds should be recycled.
-    /// @param tierIds The strictly-increasing tier set defining the group.
-    /// @param token The reward token to recycle.
-    /// @param rounds The reward rounds to recycle.
-    /// @return amount The total amount recycled.
-    function burnExpiredRewards(
-        address hook,
-        uint256[] calldata tierIds,
-        IERC20 token,
-        uint256[] calldata rounds
-    )
-        external
-        returns (uint256 amount);
-
     /// @notice Collect vested tokens from a tier-scoped reward group.
+    /// @dev Authorized NFT owners can collect to any beneficiary. Helpers can collect only to the canonical
+    /// beneficiary of every token ID they do not control.
     /// @param hook The hook whose stakers are collecting.
     /// @param tierIds The strictly-increasing tier set defining the group.
     /// @param tokenIds The IDs of the tokens to collect for.
@@ -137,7 +127,23 @@ interface IJB721Distributor is IJBDistributor, IJBSplitHook {
     /// @param amount The amount to fund.
     function fund(address hook, uint256[] calldata tierIds, IERC20 token, uint256 amount) external payable;
 
-    /// @notice Recycle unlocked rewards from burned tokens in a tier-scoped group into the current reward round.
+    /// @notice Recycle unclaimed rewards from expired tier-scoped reward rounds into the current reward round.
+    /// @param hook The hook whose expired reward rounds should be recycled.
+    /// @param tierIds The strictly-increasing tier set defining the group.
+    /// @param token The reward token to recycle.
+    /// @param rounds The reward rounds to recycle.
+    /// @return amount The total amount recycled.
+    function recycleExpiredRewards(
+        address hook,
+        uint256[] calldata tierIds,
+        IERC20 token,
+        uint256[] calldata rounds
+    )
+        external
+        returns (uint256 amount);
+
+    /// @notice Recycle rewards from burned tokens in a tier-scoped group into the current reward round as they unlock.
+    /// @dev Unclaimed historical reward shares are materialized before the unlocked forfeited amount is recycled.
     /// @param hook The hook whose tokens were burned.
     /// @param tierIds The strictly-increasing tier set defining the group.
     /// @param tokenIds The IDs of the burned tokens.