@bananapus/distributor-v6 0.0.8 → 0.0.10

package/package.json

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

package/src/JB721Distributor.sol

@@ -169,7 +169,7 @@ contract JB721Distributor is JBDistributor, IJB721Distributor {
     ///      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 being distributed.
+    /// @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.

package/src/JBDistributor.sol

@@ -10,7 +10,13 @@ import {IJBDistributor} from "./interfaces/IJBDistributor.sol";
 import {JBTokenSnapshotData} from "./structs/JBTokenSnapshotData.sol";
 import {JBVestingData} from "./structs/JBVestingData.sol";
 
-/// @notice A contract managing distributions of tokens to be claimed and vested by stakers of any other token.
+/// @notice Abstract base for reward distributors. Manages round-based distribution of ERC-20 tokens (or native ETH)
+/// to stakers with linear vesting. Each round, a snapshot is taken of the distributable balance, and stakers can
+/// claim their pro-rata share based on their stake weight at the snapshot block. Claimed tokens vest linearly over
+/// `vestingRounds` rounds and can be collected as they unlock.
+/// @dev Subclasses define how stake is measured (`_tokenStake`, `_totalStake`), who can claim (`_canClaim`), and
+/// what "burned" means (`_tokenBurned`). Two concrete implementations exist: `JBTokenDistributor` (IVotes tokens)
+/// and `JB721Distributor` (Juicebox 721 NFTs).
 abstract contract JBDistributor is IJBDistributor {
     using SafeERC20 for IERC20;
 
@@ -66,7 +72,7 @@ abstract contract JBDistributor is IJBDistributor {
     /// @notice The index within `vestingDataOf` of the latest vest.
     /// @custom:param hook The hook the tokenId belongs to.
     /// @custom:param tokenId The ID of the token to which the vests belong.
-    /// @custom:param token The address of the token being vested.
+    /// @custom:param token The address of the token vested.
     mapping(address hook => mapping(uint256 tokenId => mapping(IERC20 token => uint256))) public latestVestedIndexOf;
 
     /// @notice The block number recorded as the snapshot point for each round.
@@ -81,7 +87,7 @@ 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 tokenId The ID of the token to which the vests belong.
-    /// @custom:param token The address of the token being vested.
+    /// @custom:param token The address of the token vested.
     // slither-disable-next-line uninitialized-state
     mapping(address hook => mapping(uint256 tokenId => mapping(IERC20 token => JBVestingData[]))) public vestingDataOf;
 
@@ -100,7 +106,7 @@ abstract contract JBDistributor is IJBDistributor {
 
     /// @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 being claimed and vested.
+    /// @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;
@@ -122,10 +128,12 @@ abstract contract JBDistributor is IJBDistributor {
     // ---------------------- external transactions ---------------------- //
     //*********************************************************************//
 
-    /// @notice Claims tokens and begins vesting.
-    /// @param hook The hook whose stakers are vesting.
-    /// @param tokenIds The IDs to claim rewards for.
-    /// @param tokens The tokens to claim.
+    /// @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 `vestingRounds` rounds. Reverts if there's nothing to distribute.
+    /// @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.
     function beginVesting(address hook, uint256[] calldata tokenIds, IERC20[] calldata tokens) external override {
         // Revert if no token IDs are provided.
         if (tokenIds.length == 0) revert JBDistributor_EmptyTokenIds();
@@ -167,11 +175,13 @@ abstract contract JBDistributor is IJBDistributor {
         }
     }
 
-    /// @notice Fund the distributor for a specific hook by pulling tokens from the caller.
-    /// @dev For native ETH, send `msg.value` and pass `IERC20(JBConstants.NATIVE_TOKEN)` as the token.
-    /// @param hook The hook to fund.
+    /// @notice Directly fund the distributor for a specific hook by pulling tokens from the caller. An alternative
+    /// to split-based funding — useful for one-off deposits or external reward sources.
+    /// @dev For native ETH, send `msg.value` and pass `IERC20(JBConstants.NATIVE_TOKEN)` as the token. Uses balance
+    /// delta to handle fee-on-transfer tokens correctly.
+    /// @param hook The hook to fund (determines which staker pool receives the tokens).
     /// @param token The token to fund with.
-    /// @param amount The amount to fund.
+    /// @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 override {
         if (address(token) == JBConstants.NATIVE_TOKEN) {
             amount = msg.value;
@@ -186,16 +196,19 @@ abstract contract JBDistributor is IJBDistributor {
         _accountedBalanceOf[token] += amount;
     }
 
-    /// @notice Record the snapshot block for the current round. Callable by anyone (keepers, frontends).
+    /// @notice Record the snapshot block for the current round (and eagerly for the next round). Callable by anyone —
+    /// keepers or frontends can call this early in a round to lock the snapshot block before any claims occur.
     function poke() external override {
         _ensureSnapshotBlock(currentRound());
     }
 
-    /// @notice Release vested rewards in the case that a token was burned.
+    /// @notice Release unvested rewards tied to burned tokens. When an NFT is burned, its pending vesting entries
+    /// become stranded — this function unlocks them and returns them to the hook's distributable pool (they are NOT
+    /// sent to the beneficiary). Anyone can call this for burned tokens.
     /// @param hook The hook whose tokens were burned.
-    /// @param tokenIds The IDs of the burned tokens.
-    /// @param tokens The address of the tokens being released.
-    /// @param beneficiary The recipient of the released tokens.
+    /// @param tokenIds The IDs of the burned tokens (reverts if any are not actually burned).
+    /// @param tokens The reward tokens to release.
+    /// @param beneficiary Unused for forfeiture — tokens return to the pool. Kept for interface compatibility.
     function releaseForfeitedRewards(
         address hook,
         uint256[] calldata tokenIds,
@@ -228,11 +241,12 @@ abstract contract JBDistributor is IJBDistributor {
         return _balanceOf[hook][token];
     }
 
-    /// @notice Calculate how much of the token has been claimed for the given tokenId.
+    /// @notice Calculate the total amount of a reward token that has been claimed (began vesting) for a given
+    /// staker token ID but has not yet been collected. Includes both locked (still vesting) and unlocked amounts.
     /// @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 being claimed.
-    /// @return tokenAmount The amount of tokens that can be claimed once they have vested.
+    /// @param tokenId The ID of the staker token to calculate for.
+    /// @param token The reward token to check.
+    /// @return tokenAmount The total uncollected amount (vesting + vested-but-uncollected).
     function claimedFor(
         address hook,
         uint256 tokenId,
@@ -261,11 +275,12 @@ abstract contract JBDistributor is IJBDistributor {
         }
     }
 
-    /// @notice Calculate how much of the token is currently ready to be collected for the given tokenId.
+    /// @notice Calculate how much of a reward token is currently unlocked and ready to be collected for a given
+    /// staker token ID. Only includes the vested portion — excludes amounts still locked in vesting.
     /// @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 being claimed.
-    /// @return tokenAmount The amount of tokens that can be claimed right now.
+    /// @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 via `collectVestedRewards`.
     function collectableFor(
         address hook,
         uint256 tokenId,
@@ -306,7 +321,7 @@ 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 being claimed and vested.
+    /// @param token The address of the token claimed and vested.
     /// @param round The round to which the data applies.
     function snapshotAtRoundOf(
         address hook,
@@ -340,10 +355,12 @@ abstract contract JBDistributor is IJBDistributor {
     // ----------------------- public transactions ----------------------- //
     //*********************************************************************//
 
-    /// @notice Collect vested tokens. Auto-vests for the current round if not already vested.
+    /// @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.
     /// @param hook The hook whose stakers are collecting.
-    /// @param tokenIds The IDs of the tokens to collect for.
-    /// @param tokens The address of the tokens being claimed.
+    /// @param tokenIds The IDs of the tokens to collect for (caller must own all of them).
+    /// @param tokens The reward tokens to collect vested amounts of.
     /// @param beneficiary The recipient of the collected tokens.
     function collectVestedRewards(
         address hook,
@@ -449,7 +466,7 @@ 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 tokenIds The IDs of the tokens to unlock rewards for.
-    /// @param tokens The address of the tokens being unlocked.
+    /// @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(
@@ -504,7 +521,7 @@ 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 tokenIds The IDs of the tokens to unlock rewards for.
-    /// @param token The reward token being unlocked.
+    /// @param token The reward token to unlock.
     /// @param round The current round.
     /// @return totalTokenAmount The total amount of reward tokens unlocked.
     function _unlockTokenIds(
@@ -633,28 +650,33 @@ abstract contract JBDistributor is IJBDistributor {
     // ----------------------- internal views ---------------------------- //
     //*********************************************************************//
 
-    /// @notice A flag indicating if an account can currently claim their tokens.
+    /// @notice Check whether an account is authorized to collect vested rewards for the given token ID. For 721
+    /// distributors this is ownership; for token distributors this is address-encoding match.
     /// @param hook The hook the token belongs to.
     /// @param tokenId The ID of the token to check.
-    /// @param account The account to check if it can claim.
-    /// @return canClaim A flag indicating if claiming is allowed.
+    /// @param account The account to check authorization for.
+    /// @return canClaim True if the account can collect rewards for this token ID.
     function _canClaim(address hook, uint256 tokenId, address account) internal view virtual returns (bool canClaim);
 
-    /// @notice Checks if the given token was burned or not.
+    /// @notice Check whether a staker token has been burned. Burned tokens are excluded from stake calculations
+    /// and their unvested rewards can be released via `releaseForfeitedRewards`.
     /// @param hook The hook the token belongs to.
-    /// @param tokenId The tokenId to check.
-    /// @return tokenWasBurned A boolean that is true if the token was burned.
+    /// @param tokenId The token ID to check.
+    /// @return tokenWasBurned True if the token has been burned.
     function _tokenBurned(address hook, uint256 tokenId) internal view virtual returns (bool tokenWasBurned);
 
-    /// @notice The amount of tokens staked for the given token ID.
+    /// @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.
     /// @param hook The hook the token belongs to.
-    /// @param tokenId The ID of the token to get the staked value of.
-    /// @return tokenStakeAmount The amount of staked tokens that is being represented by the token.
+    /// @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 amount staked at the given block.
+    /// @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.
     /// @param hook The hook to get the total stake for.
-    /// @param blockNumber The block number to get the total staked amount at.
-    /// @return totalStakedAmount The total amount staked at a block number.
+    /// @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);
 }

package/src/interfaces/IJBDistributor.sol

@@ -5,7 +5,9 @@ import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
 
 import {JBTokenSnapshotData} from "../structs/JBTokenSnapshotData.sol";
 
-/// @notice A contract managing distributions of tokens to be claimed and vested by stakers of any other token.
+/// @notice Interface for round-based reward distributors with linear vesting. Stakers claim their share of a
+/// distributable balance each round, and claimed amounts vest linearly over a configurable number of rounds.
+/// Two implementations exist: `JBTokenDistributor` (IVotes token stakers) and `JB721Distributor` (NFT holders).
 interface IJBDistributor {
     //*********************************************************************//
     // -------------------------------- events --------------------------- //
@@ -14,8 +16,8 @@ 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 token The address of the token being vested.
-    /// @param amount The amount of tokens being vested.
+    /// @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.
     event Claimed(
         address indexed hook, uint256 indexed tokenId, IERC20 token, uint256 amount, uint256 vestingReleaseRound
@@ -24,7 +26,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 token The address of the token being collected.
+    /// @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.
     event Collected(
@@ -58,13 +60,13 @@ interface IJBDistributor {
     /// @notice Calculate how much of the token has been claimed for the given tokenId.
     /// @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 being claimed.
+    /// @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.
     /// @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 being claimed.
+    /// @param token The address of the token to check.
     function collectableFor(address hook, uint256 tokenId, IERC20 token) external view returns (uint256);
 
     /// @notice The number of the current round.
@@ -84,7 +86,7 @@ interface 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 being claimed and vested.
+    /// @param token The address of the token to check.
     /// @param round The round to which the data applies.
     function snapshotAtRoundOf(
         address hook,
@@ -116,7 +118,7 @@ interface IJBDistributor {
     /// @notice Collect vested tokens.
     /// @param hook The hook whose stakers are collecting.
     /// @param tokenIds The IDs of the tokens to collect for.
-    /// @param tokens The address of the tokens being claimed.
+    /// @param tokens The addresses of the tokens to collect.
     /// @param beneficiary The recipient of the collected tokens.
     function collectVestedRewards(
         address hook,
@@ -139,7 +141,7 @@ interface IJBDistributor {
     /// @notice Release vested rewards for burned tokens.
     /// @param hook The hook whose tokens were burned.
     /// @param tokenIds The IDs of the burned tokens.
-    /// @param tokens The address of the tokens being released.
+    /// @param tokens The addresses of the tokens to release.
     /// @param beneficiary The recipient of the released tokens.
     function releaseForfeitedRewards(
         address hook,

package/src/structs/JBTokenSnapshotData.sol

@@ -1,8 +1,10 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.0;
 
-/// @custom:member balance The token balance at the time of the snapshot.
-/// @custom:member vestingAmount The amount of tokens vesting at the time of the snapshot.
+/// @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;

package/src/structs/JBVestingData.sol

@@ -1,9 +1,12 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.0;
 
-/// @custom:member releaseRound The round at which the vesting tokens are fully released.
-/// @custom:member amount The original amount of tokens that were claimed.
-/// @custom:member shareClaimed The share of the amount that has already been claimed (out of `MAX_SHARE`).
+/// @notice Tracks a single vesting entry for a staker token ID. Tokens vest linearly from the claim round to
+/// `releaseRound`, and `shareClaimed` tracks how much has been collected so far (out of `MAX_SHARE = 100,000`).
+/// @custom:member releaseRound The round at which the tokens are fully vested and 100% claimable.
+/// @custom:member amount The original amount of reward tokens that were claimed (before any collection).
+/// @custom:member shareClaimed The cumulative share collected so far (out of `MAX_SHARE`). Increases each
+/// time `collectVestedRewards` is called.
 struct JBVestingData {
     uint256 releaseRound;
     uint256 amount;