@bananapus/distributor-v6 0.0.34 → 0.0.35

package/src/JBTokenDistributor.sol

@@ -60,9 +60,12 @@ contract JBTokenDistributor is JBDistributor, IJBTokenDistributor {
 
     /// @notice The next reward round a staker has not yet claimed.
     /// @custom:param hook The IVotes token whose stakers are claiming.
+    /// @custom:param groupId The reward group (0 = the default group).
     /// @custom:param tokenId The encoded staker address.
     /// @custom:param token The reward token being claimed.
-    mapping(address hook => mapping(uint256 tokenId => mapping(IERC20 token => uint256))) public nextClaimRoundOf;
+    mapping(
+        address hook => mapping(uint256 groupId => mapping(uint256 tokenId => mapping(IERC20 token => uint256)))
+    ) public nextClaimRoundOf;
 
     //*********************************************************************//
     // -------------------------- constructor ---------------------------- //
@@ -121,8 +124,8 @@ contract JBTokenDistributor is JBDistributor, IJBTokenDistributor {
             }
 
             if (msg.value != 0) {
-                // Assign native split proceeds to the current reward round for this IVotes hook.
-                _recordRewardFunding({hook: hook, token: IERC20(context.token), amount: msg.value});
+                // Split-funded pots go to the default group (0); a split cannot carry a tier set.
+                _recordRewardFunding({hook: hook, groupId: 0, token: IERC20(context.token), amount: msg.value});
             }
         } else {
             // Validate that native ETH is not cross-booked under an ERC-20 token.
@@ -139,8 +142,8 @@ contract JBTokenDistributor is JBDistributor, IJBTokenDistributor {
             uint256 delta =
                 _acceptErc20FundsFrom({token: IERC20(context.token), from: msg.sender, amount: context.amount});
 
-            // Assign only the amount actually received to this round's reward pot.
-            _recordRewardFunding({hook: hook, token: IERC20(context.token), amount: delta});
+            // Assign only the amount actually received to this round's reward pot (default group, 0).
+            _recordRewardFunding({hook: hook, groupId: 0, token: IERC20(context.token), amount: delta});
         }
     }
 
@@ -169,14 +172,28 @@ contract JBTokenDistributor is JBDistributor, IJBTokenDistributor {
     /// @param hook The IVotes token whose stakers are claiming.
     /// @param tokenIds The encoded staker addresses to claim for.
     /// @param tokens The reward tokens to claim.
-    function _claimPastRewards(address hook, uint256[] calldata tokenIds, IERC20[] calldata tokens) internal override {
+    function _claimPastRewards(
+        address hook,
+        uint256 groupId,
+        uint256[] calldata tokenIds,
+        IERC20[] calldata tokens
+    )
+        internal
+        override
+    {
         // Round 0 has no completed reward rounds behind it, so nothing can be claimed yet.
         uint256 round = currentRound();
         if (round == 0) return;
 
-        // Current-round funding is excluded. It becomes claimable only after a later round starts.
-        JBClaimContext memory ctx =
-            JBClaimContext({hook: hook, lastClaimableRound: round - 1, vestingReleaseRound: round + VESTING_ROUNDS});
+        // Current-round funding is excluded. It becomes claimable only after a later round starts. Token distributors
+        // have no tier concept, so `tierIds` stays empty; the group only isolates reward storage.
+        JBClaimContext memory ctx = JBClaimContext({
+            hook: hook,
+            groupId: groupId,
+            tierIds: new uint256[](0),
+            lastClaimableRound: round - 1,
+            vestingReleaseRound: round + VESTING_ROUNDS
+        });
 
         // Process each reward token independently because each token has its own round funding and claim cursor.
         for (uint256 i; i < tokens.length;) {
@@ -219,7 +236,7 @@ contract JBTokenDistributor is JBDistributor, IJBTokenDistributor {
         returns (uint256 tokenAmount)
     {
         // Load this staker's cursor for the reward token. All earlier rounds have already been settled.
-        uint256 nextClaimRound = nextClaimRoundOf[ctx.hook][tokenId][token];
+        uint256 nextClaimRound = nextClaimRoundOf[ctx.hook][ctx.groupId][tokenId][token];
 
         // If the cursor is already past the last completed round, this staker is current.
         if (nextClaimRound > ctx.lastClaimableRound) return 0;
@@ -227,6 +244,7 @@ contract JBTokenDistributor is JBDistributor, IJBTokenDistributor {
         // Sum this staker's pro-rata share from every unclaimed completed reward round.
         tokenAmount = _claimRewardsFor({
             hook: ctx.hook,
+            groupId: ctx.groupId,
             tokenId: tokenId,
             token: token,
             firstRound: nextClaimRound,
@@ -234,17 +252,18 @@ contract JBTokenDistributor is JBDistributor, IJBTokenDistributor {
         });
 
         // Advance the cursor even when the amount is zero, so empty or zero-stake rounds are not rescanned forever.
-        nextClaimRoundOf[ctx.hook][tokenId][token] = ctx.lastClaimableRound + 1;
+        nextClaimRoundOf[ctx.hook][ctx.groupId][tokenId][token] = ctx.lastClaimableRound + 1;
         if (tokenAmount == 0) return 0;
 
         // All accumulated past rewards start a single fresh vesting schedule at the claim round.
-        vestingDataOf[ctx.hook][tokenId][token].push(
+        vestingDataOf[ctx.hook][ctx.groupId][tokenId][token].push(
             JBVestingData({releaseRound: ctx.vestingReleaseRound, amount: tokenAmount, shareClaimed: 0})
         );
 
         emit Claimed({
             hook: ctx.hook,
             tokenId: tokenId,
+            groupId: ctx.groupId,
             token: token,
             amount: tokenAmount,
             vestingReleaseRound: ctx.vestingReleaseRound,
@@ -265,6 +284,7 @@ contract JBTokenDistributor is JBDistributor, IJBTokenDistributor {
     /// @return tokenAmount The cumulative unclaimed reward amount.
     function _claimRewardsFor(
         address hook,
+        uint256 groupId,
         uint256 tokenId,
         IERC20 token,
         uint256 firstRound,
@@ -275,14 +295,14 @@ contract JBTokenDistributor is JBDistributor, IJBTokenDistributor {
     {
         // 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 and reward token.
-            JBRewardRoundData storage rewardRound = rewardRoundOf[hook][token][rewardRoundNumber];
+            // Load this round's reward data for the hook, group, and reward token.
+            JBRewardRoundData storage rewardRound = rewardRoundOf[hook][groupId][token][rewardRoundNumber];
 
             // Skip rounds that never received funding.
             if (rewardRound.amount != 0) {
                 // Expired rounds can no longer be claimed as-is; recycle their unclaimed remainder instead.
                 if (_rewardRoundExpired(rewardRound)) {
-                    _recycleExpiredRewardRound({hook: hook, token: token, round: rewardRoundNumber});
+                    _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 =
@@ -350,11 +370,23 @@ contract JBTokenDistributor is JBDistributor, IJBTokenDistributor {
     }
 
     /// @notice The total supply of votes at a specific block.
-    /// @dev Uses `IVotes.getPastTotalSupply` for checkpointed lookups.
+    /// @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 blockNumber) internal view override returns (uint256 totalStakedAmount) {
+    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);
     }
 

package/src/interfaces/IJB721Distributor.sol

@@ -3,13 +3,152 @@ pragma solidity ^0.8.0;
 
 import {IJBDirectory} from "@bananapus/core-v6/src/interfaces/IJBDirectory.sol";
 import {IJBSplitHook} from "@bananapus/core-v6/src/interfaces/IJBSplitHook.sol";
+import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
 
 import {IJBDistributor} from "./IJBDistributor.sol";
 
 /// @notice A singleton distributor that distributes ERC-20 rewards to JB 721 NFT stakers with linear vesting.
 /// @dev Also implements `IJBSplitHook` to receive tokens from payout splits.
 /// @dev Projects configure their split with `hook = distributor` and `beneficiary = their721Hook`.
+/// @dev Adds tier-scoped reward groups on top of the generic group plumbing: a group is a strictly-increasing tier
+/// set, and only NFTs whose tier is in the set can claim that group's pot.
 interface IJB721Distributor is IJBDistributor, IJBSplitHook {
+    //*********************************************************************//
+    // ----------------------------- views ------------------------------- //
+    //*********************************************************************//
+
     /// @notice The JB directory used to verify terminal/controller callers.
     function DIRECTORY() external view returns (IJBDirectory);
+
+    /// @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.
+    function claimedFor(
+        address hook,
+        uint256[] calldata tierIds,
+        uint256 tokenId,
+        IERC20 token
+    )
+        external
+        view
+        returns (uint256);
+
+    /// @notice Calculate how much of the token is currently ready to be collected 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.
+    function collectableFor(
+        address hook,
+        uint256[] calldata tierIds,
+        uint256 tokenId,
+        IERC20 token
+    )
+        external
+        view
+        returns (uint256);
+
+    /// @notice The tier set that defines a reward group, recorded when the group is first funded.
+    /// @dev Empty for the all-tiers group (0).
+    /// @param hook The hook the group belongs to.
+    /// @param groupId The reward group.
+    /// @return tierIds The strictly-increasing tier set defining the group.
+    function tierIdsOf(address hook, uint256 groupId) external view returns (uint256[] memory tierIds);
+
+    //*********************************************************************//
+    // ---------------------------- transactions ------------------------- //
+    //*********************************************************************//
+
+    /// @notice Claims tokens and begins vesting from a tier-scoped reward group.
+    /// @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.
+    /// @param tokens The tokens to claim.
+    function beginVesting(
+        address hook,
+        uint256[] calldata tierIds,
+        uint256[] calldata tokenIds,
+        IERC20[] calldata tokens
+    )
+        external;
+
+    /// @notice Borrow against one token ID's uncollected vesting rewards in a tier-scoped group.
+    /// @param hook The hook whose staker is borrowing against vesting rewards.
+    /// @param tierIds The strictly-increasing tier set defining the 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 borrowAgainstVesting(
+        address hook,
+        uint256[] calldata tierIds,
+        uint256[] calldata tokenIds,
+        IERC20[] calldata tokens,
+        address sourceToken,
+        uint256 minBorrowAmount,
+        uint256 prepaidFeePercent,
+        address payable beneficiary
+    )
+        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.
+    /// @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.
+    /// @param tokens The addresses of the tokens to collect.
+    /// @param beneficiary The recipient of the collected tokens.
+    function collectVestedRewards(
+        address hook,
+        uint256[] calldata tierIds,
+        uint256[] calldata tokenIds,
+        IERC20[] calldata tokens,
+        address beneficiary
+    )
+        external;
+
+    /// @notice Fund a tier-scoped reward group: only holders of the given tiers can claim this pot.
+    /// @dev For native ETH, send `msg.value` and pass `IERC20(NATIVE_TOKEN)` as the token.
+    /// @param hook The hook to fund.
+    /// @param tierIds The strictly-increasing tier set defining the group.
+    /// @param token The token to fund with.
+    /// @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.
+    /// @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.
+    /// @param tokens The reward tokens to recycle.
+    /// @param beneficiary Unused for forfeiture.
+    function releaseForfeitedRewards(
+        address hook,
+        uint256[] calldata tierIds,
+        uint256[] calldata tokenIds,
+        IERC20[] calldata tokens,
+        address beneficiary
+    )
+        external;
 }

package/src/interfaces/IJBDistributor.sol

@@ -45,6 +45,7 @@ interface IJBDistributor {
     /// @notice Emitted when a staker begins vesting tokens.
     /// @param hook The hook whose stakers are vesting.
     /// @param tokenId The ID of the staked token that is claiming.
+    /// @param groupId The reward group claimed from (0 = the default group).
     /// @param token The address of the token to vest.
     /// @param amount The amount of tokens to vest.
     /// @param vestingReleaseRound The round at which the tokens will be fully released.
@@ -52,6 +53,7 @@ interface IJBDistributor {
     event Claimed(
         address indexed hook,
         uint256 indexed tokenId,
+        uint256 groupId,
         IERC20 token,
         uint256 amount,
         uint256 vestingReleaseRound,
@@ -61,6 +63,7 @@ interface IJBDistributor {
     /// @notice Emitted when vested tokens are collected.
     /// @param hook The hook whose stakers are collecting.
     /// @param tokenId The ID of the staked token collecting.
+    /// @param groupId The reward group collected from (0 = the default group).
     /// @param token The address of the token collected.
     /// @param amount The amount of tokens collected.
     /// @param vestingReleaseRound The round at which the tokens will be fully released.
@@ -68,6 +71,7 @@ interface IJBDistributor {
     event Collected(
         address indexed hook,
         uint256 indexed tokenId,
+        uint256 groupId,
         IERC20 token,
         uint256 amount,
         uint256 vestingReleaseRound,
@@ -171,17 +175,27 @@ interface IJBDistributor {
 
     /// @notice The active Revnet loan using one token ID's vesting rewards as collateral.
     /// @param hook The hook the token ID belongs to.
+    /// @param groupId The reward group (0 = the default group).
     /// @param tokenId The token ID whose vesting rewards are collateralized.
     /// @param token The reward token used as loan collateral.
-    function activeVestingLoanIdOf(address hook, uint256 tokenId, IERC20 token) external view returns (uint256);
+    function activeVestingLoanIdOf(
+        address hook,
+        uint256 groupId,
+        uint256 tokenId,
+        IERC20 token
+    )
+        external
+        view
+        returns (uint256);
 
-    /// @notice Calculate how much of the token has been claimed for the given tokenId.
+    /// @notice Calculate how much of the token has been claimed for the given tokenId in the default group.
     /// @param hook The hook the tokenId belongs to.
     /// @param tokenId The ID of the token to calculate the token amount for.
     /// @param token The address of the token to check.
     function claimedFor(address hook, uint256 tokenId, IERC20 token) external view returns (uint256);
 
-    /// @notice Calculate how much of the token is currently ready to be collected for the given tokenId.
+    /// @notice Calculate how much of the token is currently ready to be collected for the given tokenId in the
+    /// default group.
     /// @param hook The hook the tokenId belongs to.
     /// @param tokenId The ID of the token to calculate the token amount for.
     /// @param token The address of the token to check.
@@ -217,7 +231,7 @@ interface IJBDistributor {
     // ---------------------------- transactions ------------------------- //
     //*********************************************************************//
 
-    /// @notice Claims tokens and begins vesting.
+    /// @notice Claims tokens and begins vesting from the default group.
     /// @param hook The hook whose stakers are vesting.
     /// @param tokenIds The IDs to claim rewards for.
     /// @param tokens The tokens to claim.
@@ -245,7 +259,7 @@ interface IJBDistributor {
         external
         returns (uint256 loanId, uint256 collateralCount);
 
-    /// @notice Collect vested tokens.
+    /// @notice Collect vested tokens from the default group.
     /// @param hook The hook whose stakers are collecting.
     /// @param tokenIds The IDs of the tokens to collect for.
     /// @param tokens The addresses of the tokens to collect.
@@ -258,14 +272,14 @@ interface IJBDistributor {
     )
         external;
 
-    /// @notice Fund the distributor for a specific hook.
+    /// @notice Fund the distributor's default group for a specific hook.
     /// @dev For native ETH, send `msg.value` and pass `IERC20(NATIVE_TOKEN)` as the token.
     /// @param hook The hook to fund.
     /// @param token The token to fund with.
     /// @param amount The amount to fund.
     function fund(address hook, IERC20 token, uint256 amount) external payable;
 
-    /// @notice Recycle unclaimed rewards from expired reward rounds into the current reward round.
+    /// @notice Recycle unclaimed rewards from expired default-group reward rounds into the current reward round.
     /// @param hook The hook whose expired reward rounds should be recycled.
     /// @param token The reward token to recycle.
     /// @param rounds The reward rounds to recycle.
@@ -287,7 +301,7 @@ interface IJBDistributor {
         payable
         returns (uint256 paidOffLoanId);
 
-    /// @notice Recycle unlocked rewards from burned tokens into the current reward round.
+    /// @notice Recycle unlocked rewards from burned tokens in the default group into the current reward round.
     /// @param hook The hook whose tokens were burned.
     /// @param tokenIds The IDs of the burned tokens.
     /// @param tokens The reward tokens to recycle.

package/src/structs/JBBorrowContext.sol

@@ -5,6 +5,7 @@ import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
 
 /// @notice Parameters used while opening a distributor-owned Revnet loan.
 /// @custom:member hook The hook whose token ID owns the vesting rewards.
+/// @custom:member groupId The reward group whose vesting rewards are collateralized (0 = the default group).
 /// @custom:member tokenId The token ID whose vesting rewards are collateralized.
 /// @custom:member token The revnet reward token used as loan collateral.
 /// @custom:member sourceToken The token borrowed from the revnet.
@@ -14,6 +15,7 @@ import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
 /// @custom:member revnetId The revnet whose project token is collateralized.
 struct JBBorrowContext {
     address hook;
+    uint256 groupId;
     uint256 tokenId;
     IERC20 token;
     address sourceToken;

package/src/structs/JBClaimContext.sol

@@ -2,10 +2,15 @@
 pragma solidity ^0.8.0;
 
 /// @custom:member hook The stake source whose historical rewards are being claimed.
+/// @custom:member groupId The reward group being claimed (0 = the default group).
+/// @custom:member tierIds The tier set defining the group (empty for the default group); used to filter eligible
+/// token IDs on the tier-scoped path.
 /// @custom:member lastClaimableRound The last completed reward round included in the claim.
 /// @custom:member vestingReleaseRound The round at which newly materialized rewards finish vesting.
 struct JBClaimContext {
     address hook;
+    uint256 groupId;
+    uint256[] tierIds;
     uint256 lastClaimableRound;
     uint256 vestingReleaseRound;
 }

package/src/structs/JBVestContext.sol

@@ -4,6 +4,9 @@ pragma solidity ^0.8.0;
 import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
 
 /// @custom:member hook The stake source whose rewards are being vested.
+/// @custom:member groupId The reward group being claimed (0 = the default group).
+/// @custom:member tierIds The tier set defining the group (empty for the default group); used to filter eligible
+/// token IDs on the tier-scoped path.
 /// @custom:member token The reward token being vested.
 /// @custom:member distributable The reward amount assigned to the round.
 /// @custom:member totalStakeAmount The total checkpointed stake sharing the round's rewards.
@@ -12,6 +15,8 @@ import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
 /// @custom:member snapshotBlock The block used for historical stake and ownership lookups.
 struct JBVestContext {
     address hook;
+    uint256 groupId;
+    uint256[] tierIds;
     IERC20 token;
     uint256 distributable;
     uint256 totalStakeAmount;

package/src/structs/JBVestingLoan.sol

@@ -5,12 +5,14 @@ import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
 
 /// @notice Tracks a Revnet loan collateralized by one token ID's vesting rewards.
 /// @custom:member hook The hook the token ID belongs to.
+/// @custom:member groupId The reward group whose vesting rewards are collateralized (0 = the default group).
 /// @custom:member tokenId The token ID whose vesting rewards are collateralized.
 /// @custom:member token The revnet reward token used as loan collateral.
 /// @custom:member vestingDataCount The vesting-entry boundary collateralized by the loan.
 /// @custom:member collateralCount The amount of vesting rewards collateralized.
 struct JBVestingLoan {
     address hook;
+    uint256 groupId;
     uint256 tokenId;
     IERC20 token;
     uint48 vestingDataCount;