@bananapus/distributor-v6 0.0.36 → 0.0.38

package/README.md

@@ -30,7 +30,7 @@ Use this repo when the problem is "how do we distribute already-owned assets ove
 
 If the issue is "where did the project's value come from?" start in `nana-core-v6`, `nana-721-hook-v6`, or the upstream repo that minted or received the assets first.
 
-## Key Contracts
+## Key contracts
 
 | Contract | Role |
 | --- | --- |
@@ -38,7 +38,7 @@ If the issue is "where did the project's value come from?" start in `nana-core-v
 | `JBTokenDistributor` | ERC-20 distributor keyed to `IVotes` checkpointed voting power. |
 | `JB721Distributor` | NFT-aware distributor keyed to checkpointed voting power from the hook's `CHECKPOINTS()` module. Only NFTs held at the funded round's snapshot block are eligible. |
 
-## Mental Model
+## Mental model
 
 1. a project funds the distributor, often through a payout split
 2. accepted funding is assigned to the current reward round for the chosen token or 721 stake source
@@ -51,14 +51,14 @@ If the issue is "where did the project's value come from?" start in `nana-core-v
 
 This repo does not explain why an allocation exists. It only defines how funded inventory is handed out.
 
-## Read These Files First
+## Read these files first
 
 1. `src/interfaces/IJBDistributor.sol`
 2. `src/JBDistributor.sol`
 3. `src/JBTokenDistributor.sol`
 4. `src/JB721Distributor.sol`
 
-## Integration Traps
+## Integration traps
 
 - distribution correctness depends on the distributor actually holding the assets it is expected to vest
 - ERC-20 and ERC-721 distributions share historical reward-round accounting, but claim authority differs:
@@ -87,14 +87,14 @@ This repo does not explain why an allocation exists. It only defines how funded
 - snapshot timing is part of the trusted surface
 - this repo settles distributions, but it does not prove the upstream entitlement math was correct
 
-## Where State Lives
+## Where state lives
 
 - round and vesting state: `JBDistributor`
 - historical reward-round inputs: `JBRewardRoundData`
 - vesting schedule state: `JBVestingData`
 - asset-specific claim behavior: the concrete distributor
 
-## High-Signal Tests
+## High-signal tests
 
 1. `test/JBTokenDistributor.t.sol`
 2. `test/JB721Distributor.t.sol`
@@ -121,7 +121,7 @@ Useful scripts:
 - `npm run deploy:mainnets`
 - `npm run deploy:testnets`
 
-## Repository Layout
+## Repository layout
 
 ```text
 src/
@@ -136,7 +136,7 @@ script/
   Deploy.s.sol
 ```
 
-## Risks And Notes
+## Risks and notes
 
 - distributors are only as trustworthy as the vesting parameters and funding they receive
 - operational mistakes often come from funding the wrong asset or underfunding the distributor
@@ -144,7 +144,7 @@ script/
 - deployers that set a nonzero claim duration should choose a window long enough for expected claimants, because
   expired unclaimed rewards can be recycled by anyone
 
-## For AI Agents
+## For AI agents
 
 - Treat this repo as distribution plumbing, not as the source of upstream entitlement math.
 - Read both the ERC-20 and ERC-721 tests before claiming the flows are equivalent.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/distributor-v6",
-  "version": "0.0.36",
+  "version": "0.0.38",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -24,12 +24,12 @@
     "deploy:testnets": "source ./.env && npx sphinx propose ./script/Deploy.s.sol --networks testnets"
   },
   "dependencies": {
-    "@bananapus/721-hook-v6": "^0.0.63",
-    "@bananapus/core-v6": "^0.0.72",
-    "@bananapus/permission-ids-v6": "^0.0.27",
+    "@bananapus/721-hook-v6": "^0.0.65",
+    "@bananapus/core-v6": "^0.0.78",
+    "@bananapus/permission-ids-v6": "^0.0.28",
     "@openzeppelin/contracts": "5.6.1",
     "@prb/math": "4.1.1",
-    "@rev-net/core-v6": "^0.0.75"
+    "@rev-net/core-v6": "^0.0.84"
   },
   "devDependencies": {
     "@sphinx-labs/plugins": "0.33.3"

package/references/operations.md

@@ -20,7 +20,7 @@
 | 721 reward shares look diluted | Burned supply was not excluded correctly or token-to-tier mapping is wrong |
 | Split-hook funding credits the wrong amount | The caller did not grant a sufficient ERC-20 allowance before calling `processSplitWith` |
 
-## Read Next
+## Read next
 
 - [`script/Deploy.s.sol`](../script/Deploy.s.sol) when the failure might be deployment config rather than distributor math.
 - [`test/invariant/JB721DistributorInvariant.t.sol`](../test/invariant/JB721DistributorInvariant.t.sol) when a local patch looks safe but may have broken a longer-lived accounting invariant.

package/src/JBDistributor.sol

@@ -163,6 +163,7 @@ abstract contract JBDistributor is IJBDistributor {
 
     /// @notice The block number recorded as the snapshot point for each round.
     /// @dev Set to `block.number - 1` on first interaction in a round, so that `IVotes.getPastVotes` works.
+    /// @custom:param round The round whose snapshot block is being recorded.
     mapping(uint256 round => uint256) public override roundSnapshotBlock;
 
     /// @notice Reward data assigned to each funding round.
@@ -296,7 +297,7 @@ abstract contract JBDistributor is IJBDistributor {
     }
 
     /// @notice Recycle unclaimed rewards from expired reward rounds into the current reward round.
-    /// @dev The selector name is kept for compatibility with existing keeper integrations.
+    /// @dev Recycling is permissionless; any keeper or frontend can sweep an expired round.
     /// @param hook The hook whose expired rewards should be recycled.
     /// @param token The reward token to recycle.
     /// @param rounds The reward rounds to recycle.
@@ -633,7 +634,7 @@ abstract contract JBDistributor is IJBDistributor {
         // Before collecting, bring the token IDs current by starting vesting for any past reward rounds.
         _claimPastRewards({hook: hook, groupId: groupId, tokenIds: tokenIds, tokens: tokens});
 
-        // Release whatever portion of existing vesting entries has unlocked by this round.
+        // Release whatever portion of vesting entries has unlocked by this round.
         _unlockRewards({
             hook: hook, groupId: groupId, tokenIds: tokenIds, tokens: tokens, beneficiary: beneficiary, ownerClaim: true
         });
@@ -911,7 +912,7 @@ abstract contract JBDistributor is IJBDistributor {
                 revert JBDistributor_UnexpectedNativeValue({msgValue: msg.value, token: loan.sourceToken});
             }
 
-            // Pull the exact current payoff from the caller. Existing distributor inventory must not cover a shortfall.
+            // Pull the exact current payoff from the caller. Distributor inventory must not cover a shortfall.
             IERC20 sourceToken = IERC20(loan.sourceToken);
             uint256 sourceBalanceBefore = sourceToken.balanceOf(address(this));
             sourceToken.safeTransferFrom({from: msg.sender, to: address(this), value: repayBorrowAmount});
@@ -1263,7 +1264,7 @@ abstract contract JBDistributor is IJBDistributor {
     /// @param round The reward round.
     /// @return claimDeadline The deadline timestamp. Zero means no expiration.
     function _claimDeadlineFor(uint256 round) internal view returns (uint48 claimDeadline) {
-        // Zero duration keeps the round non-expiring and backward compatible with existing fund paths.
+        // A zero claim duration means the round never expires.
         if (CLAIM_DURATION == 0) return 0;
 
         // Start the window at the next round boundary, when the funded round first becomes claimable.

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.

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/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