@bananapus/distributor-v6 0.0.37 → 0.0.42

package/src/interfaces/IJBDistributor.sol

@@ -148,36 +148,45 @@ interface IJBDistributor {
 
     /// @notice The number of seconds after a reward round becomes claimable before unclaimed rewards expire.
     /// @dev A zero duration means reward rounds do not expire.
-    function CLAIM_DURATION() external view returns (uint48);
+    /// @return claimDuration The claim duration, in seconds.
+    function CLAIM_DURATION() external view returns (uint48 claimDuration);
 
     /// @notice The JB controller used for token registry lookups and revnet loan permissions.
-    function CONTROLLER() external view returns (IJBController);
+    /// @return controller The JB controller.
+    function CONTROLLER() external view returns (IJBController controller);
 
     /// @notice The duration of each round, specified in seconds.
-    function ROUND_DURATION() external view returns (uint256);
+    /// @return roundDuration The round duration, in seconds.
+    function ROUND_DURATION() external view returns (uint256 roundDuration);
 
     /// @notice The Revnet loans contract used to borrow against vesting revnet rewards.
-    function REV_LOANS() external view returns (IREVLoans);
+    /// @return revLoans The Revnet loans contract.
+    function REV_LOANS() external view returns (IREVLoans revLoans);
 
     /// @notice The REVOwner contract that must own a reward token's project to enable loan-backed collection.
-    function REV_OWNER() external view returns (IREVOwner);
+    /// @return revOwner The REVOwner contract.
+    function REV_OWNER() external view returns (IREVOwner revOwner);
 
     /// @notice The starting timestamp of the distributor.
-    function STARTING_TIMESTAMP() external view returns (uint256);
+    /// @return startingTimestamp The starting timestamp.
+    function STARTING_TIMESTAMP() external view returns (uint256 startingTimestamp);
 
     /// @notice The number of rounds until tokens are fully vested.
-    function VESTING_ROUNDS() external view returns (uint256);
+    /// @return vestingRounds The number of rounds until tokens are fully vested.
+    function VESTING_ROUNDS() external view returns (uint256 vestingRounds);
 
     /// @notice The balance of a token held for a specific hook's stakers.
     /// @param hook The hook whose balance to check.
     /// @param token The token to check the balance of.
-    function balanceOf(address hook, IERC20 token) external view returns (uint256);
+    /// @return balance The token balance held for the hook.
+    function balanceOf(address hook, IERC20 token) external view returns (uint256 balance);
 
     /// @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.
+    /// @return loanId The active Revnet loan NFT ID, or 0 if none is active.
     function activeVestingLoanIdOf(
         address hook,
         uint256 groupId,
@@ -186,52 +195,60 @@ interface IJBDistributor {
     )
         external
         view
-        returns (uint256);
+        returns (uint256 loanId);
 
     /// @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);
+    /// @return tokenAmount The claimed token amount.
+    function claimedFor(address hook, uint256 tokenId, IERC20 token) external view returns (uint256 tokenAmount);
 
-    /// @notice Calculate how much of the token is currently ready to be collected for the given tokenId in the
-    /// default group.
+    /// @notice Calculate the collectible token amount for a token ID 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 collectableFor(address hook, uint256 tokenId, IERC20 token) external view returns (uint256);
+    /// @return tokenAmount The currently collectable token amount.
+    function collectableFor(address hook, uint256 tokenId, IERC20 token) external view returns (uint256 tokenAmount);
 
     /// @notice The number of the current round.
-    function currentRound() external view returns (uint256);
+    /// @return round The current round number.
+    function currentRound() external view returns (uint256 round);
 
     /// @notice The block number recorded as the snapshot point for a round.
     /// @dev Returns 0 if no snapshot block has been recorded yet for this round.
     /// @param round The round to get the snapshot block of.
-    function roundSnapshotBlock(uint256 round) external view returns (uint256);
+    /// @return snapshotBlock The snapshot block recorded for the round.
+    function roundSnapshotBlock(uint256 round) external view returns (uint256 snapshotBlock);
 
     /// @notice The timestamp at which a round started.
     /// @param round The round to get the start timestamp of.
-    function roundStartTimestamp(uint256 round) external view returns (uint256);
+    /// @return timestamp The round's start timestamp.
+    function roundStartTimestamp(uint256 round) external view returns (uint256 timestamp);
 
     /// @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.
-    function totalVestingAmountOf(address hook, IERC20 token) external view returns (uint256);
+    /// @return tokenAmount The amount of the token currently vesting.
+    function totalVestingAmountOf(address hook, IERC20 token) external view returns (uint256 tokenAmount);
 
     /// @notice The amount of vesting inventory currently collateralized in Revnet loans.
     /// @param hook The hook whose loaned vesting amount to check.
     /// @param token The reward token used as collateral.
-    function totalLoanedVestingAmountOf(address hook, IERC20 token) external view returns (uint256);
+    /// @return tokenAmount The amount of the token currently collateralized in loans.
+    function totalLoanedVestingAmountOf(address hook, IERC20 token) external view returns (uint256 tokenAmount);
 
     /// @notice The vesting position collateralized by a Revnet loan.
     /// @param loanId The Revnet loan NFT ID.
-    function vestingLoanOf(uint256 loanId) external view returns (JBVestingLoan memory);
+    /// @return vestingLoan The vesting loan data.
+    function vestingLoanOf(uint256 loanId) external view returns (JBVestingLoan memory vestingLoan);
 
     //*********************************************************************//
     // ---------------------------- transactions ------------------------- //
     //*********************************************************************//
 
     /// @notice Claims tokens and begins vesting from the default group.
+    /// @dev Permissionless. No reward tokens leave the distributor.
     /// @param hook The hook whose stakers are vesting.
     /// @param tokenIds The IDs to claim rewards for.
     /// @param tokens The tokens to claim.
@@ -260,6 +277,8 @@ interface IJBDistributor {
         returns (uint256 loanId, uint256 collateralCount);
 
     /// @notice Collect vested tokens from the default group.
+    /// @dev Authorized holders 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 tokenIds The IDs of the tokens to collect for.
     /// @param tokens The addresses of the tokens to collect.
@@ -279,29 +298,24 @@ interface IJBDistributor {
     /// @param amount The amount to fund.
     function fund(address hook, IERC20 token, uint256 amount) external payable;
 
+    /// @notice Record the snapshot block for the current round. Callable by anyone (keepers, frontends).
+    function poke() external;
+
     /// @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.
     /// @return amount The total amount recycled.
-    function burnExpiredRewards(address hook, IERC20 token, uint256[] calldata rounds) external returns (uint256 amount);
-
-    /// @notice Record the snapshot block for the current round. Callable by anyone (keepers, frontends).
-    function poke() external;
-
-    /// @notice Repay a distributor-held Revnet loan and restore its collateral to the original vesting schedule.
-    /// @param loanId The Revnet loan NFT ID to repay.
-    /// @param maxRepayBorrowAmount The maximum amount of source token the caller is willing to repay.
-    /// @return paidOffLoanId The paid-off loan ID returned by Revnet loans.
-    function repayVestingLoan(
-        uint256 loanId,
-        uint256 maxRepayBorrowAmount
+    function recycleExpiredRewards(
+        address hook,
+        IERC20 token,
+        uint256[] calldata rounds
     )
         external
-        payable
-        returns (uint256 paidOffLoanId);
+        returns (uint256 amount);
 
-    /// @notice Recycle unlocked rewards from burned tokens in the default group into the current reward round.
+    /// @notice Recycle rewards from burned tokens in the default 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 tokenIds The IDs of the burned tokens.
     /// @param tokens The reward tokens to recycle.
@@ -314,6 +328,18 @@ interface IJBDistributor {
     )
         external;
 
+    /// @notice Repay a distributor-held Revnet loan and restore its collateral to the original vesting schedule.
+    /// @param loanId The Revnet loan NFT ID to repay.
+    /// @param maxRepayBorrowAmount The maximum amount of source token the caller is willing to repay.
+    /// @return paidOffLoanId The paid-off loan ID returned by Revnet loans.
+    function repayVestingLoan(
+        uint256 loanId,
+        uint256 maxRepayBorrowAmount
+    )
+        external
+        payable
+        returns (uint256 paidOffLoanId);
+
     /// @notice Write off a distributor-held Revnet loan after Revnet liquidation permanently destroys its collateral.
     /// @param loanId The liquidated Revnet loan NFT ID.
     /// @return collateralCount The amount of vesting rewards forfeited by liquidation.

package/src/interfaces/IJBTokenDistributor.sol

@@ -6,11 +6,12 @@ import {IJBSplitHook} from "@bananapus/core-v6/src/interfaces/IJBSplitHook.sol";
 
 import {IJBDistributor} from "./IJBDistributor.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 Also implements `IJBSplitHook` to receive tokens from payout splits.
 /// @dev Projects configure their split with `hook = distributor` and `beneficiary = their IVotes token`.
 interface IJBTokenDistributor 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);
 }

package/src/libraries/JBVestingMath.sol

@@ -6,7 +6,8 @@ import {mulDiv} from "@prb/math/src/Common.sol";
 /// @notice Pure helpers for the distributor's linear vesting arithmetic.
 library JBVestingMath {
     /// @notice The share still locked for a vesting entry at `currentRound`.
-    /// @dev Mirrors the distributor's existing linear vesting formula. Callers maintain the invariant that
+    /// @dev Linear release: the locked share shrinks one `maxShare/vestingRounds` step per round. Callers maintain
+    /// the invariant that
     /// `releaseRound - currentRound <= vestingRounds` whenever `releaseRound > currentRound`.
     /// @param releaseRound The round when the entry is fully unlocked.
     /// @param currentRound The current distributor round.
@@ -54,7 +55,7 @@ library JBVestingMath {
         }
     }
 
-    /// @notice The amount remaining after the previously claimed share is deducted.
+    /// @notice The amount remaining after the already claimed share is deducted.
     /// @dev Computing `amount - paid` releases any floor-division dust on the final unlock.
     /// @param amount The original vesting entry amount.
     /// @param shareClaimed The cumulative share already claimed.

package/src/structs/JBClaimContext.sol

@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.0;
 
+/// @notice Parameters describing one lazy claim of completed reward rounds into a fresh vesting entry.
 /// @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

package/src/structs/JBRewardRoundData.sol

@@ -5,8 +5,8 @@ pragma solidity ^0.8.0;
 /// @custom:member amount The reward amount assigned to the round.
 /// @custom:member snapshotBlock The block used for per-account historical stake lookups.
 /// @custom:member claimedAmount The reward amount already materialized into vesting.
-/// @custom:member claimDeadline The timestamp at which unclaimed rewards can be recycled. Zero means no expiration.
-/// @custom:member totalStake The aggregate stake at the round's snapshot block.
+/// @custom:member claimDeadline The timestamp used by distributor-specific expiration logic. Zero means no expiration.
+/// @custom:member totalStake The aggregate stake denominator used to split the round.
 struct JBRewardRoundData {
     uint208 amount;
     uint48 snapshotBlock;

package/src/structs/JBVestContext.sol

@@ -3,6 +3,7 @@ pragma solidity ^0.8.0;
 
 import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
 
+/// @notice Parameters describing one round's reward allocation while vesting begins.
 /// @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