@bananapus/distributor-v6 0.0.31 → 0.0.33

package/README.md

@@ -2,12 +2,17 @@
 
 `@bananapus/distributor-v6` distributes ERC-20 balances or 721 token inventories to many recipients under round-based vesting rules. It is a payout utility package for Juicebox-adjacent flows, not a protocol accounting layer.
 
-Architecture: [ARCHITECTURE.md](./ARCHITECTURE.md)  
-User journeys: [USER_JOURNEYS.md](./USER_JOURNEYS.md)  
-Skills: [SKILLS.md](./SKILLS.md)  
-Risks: [RISKS.md](./RISKS.md)  
-Administration: [ADMINISTRATION.md](./ADMINISTRATION.md)  
-Audit instructions: [AUDIT_INSTRUCTIONS.md](./AUDIT_INSTRUCTIONS.md)
+## Documentation
+
+- [ARCHITECTURE.md](./ARCHITECTURE.md) — system overview, modules, trust boundaries, and core invariants.
+- [USER_JOURNEYS.md](./USER_JOURNEYS.md) — end-to-end flows for funders and claimants across token and 721 variants.
+- [INVARIANTS.md](./INVARIANTS.md) — per-section invariants for snapshot fairness, vesting math, claim authority, loans, and recycling.
+- [RISKS.md](./RISKS.md) — risk register with priority risks and the minimum invariants to verify.
+- [ADMINISTRATION.md](./ADMINISTRATION.md) — deployment parameters, control posture, and recovery guidance.
+- [SKILLS.md](./SKILLS.md) — quick index for routing tasks into the right sub-document.
+- [STYLE_GUIDE.md](./STYLE_GUIDE.md) — Solidity and repo conventions used across the Juicebox V6 ecosystem.
+- [AUDIT_INSTRUCTIONS.md](./AUDIT_INSTRUCTIONS.md) — audit framing, targets, and suggested hunting grounds.
+- [CHANGELOG.md](./CHANGELOG.md) — release notes and dependency bumps.
 
 ## Overview
 
@@ -39,10 +44,10 @@ If the issue is "where did the project's value come from?" start in `nana-core-v
 2. accepted funding is assigned to the current reward round for the chosen token or 721 stake source
 3. the distributor's immutable claim duration decides whether funded reward rounds expire
 4. the encoded token staker or current NFT owner later claims completed past reward rounds into a fresh vesting entry
-5. anyone can burn expired unclaimed reward rounds after their deadline
+5. anyone can recycle expired unclaimed reward rounds after their deadline
 6. recipients collect their vested share as the configured vesting schedule unlocks
 7. eligible claimants can borrow against vesting revnet rewards without bypassing the vesting schedule
-8. some unclaimable value can be burned through explicit cleanup paths, depending on the distributor type
+8. some unclaimable value can be recycled through explicit cleanup paths, depending on the distributor type
 
 This repo does not explain why an allocation exists. It only defines how funded inventory is handed out.
 
@@ -60,10 +65,9 @@ This repo does not explain why an allocation exists. It only defines how funded
   token rewards are claimed by the encoded staker address, while 721 rewards are claimed by the current NFT owner
 - `CLAIM_DURATION` is fixed at deployment; `0` means reward rounds do not expire, otherwise all funding paths use the
   same deadline measured from when the funded round first becomes claimable
-- `burnExpiredRewards` is permissionless and only burns the unclaimed remainder; already-materialized vesting entries
+- `burnExpiredRewards` is permissionless and only recycles the unclaimed remainder; already-materialized vesting entries
   remain claimable on their normal vesting curve
-- expired and forfeited rewards are burned with `JBController.burnTokensOf`; rewards that are not registered project
-  tokens in the configured controller cannot use those burn paths
+- expired and forfeited rewards stay in distributor inventory and are recycled into the current reward round
 - revnet loan-backed vesting is opt-in at deployment; the reward token must be a REVOwner-owned revnet token, the
   distributor keeps the loan NFT, and repayment restores the original vesting schedule instead of releasing all
   collateral immediately
@@ -131,7 +135,7 @@ script/
 - operational mistakes often come from funding the wrong asset or underfunding the distributor
 - teams should review claim timing and snapshot assumptions with the same care they review the payout source
 - deployers that set a nonzero claim duration should choose a window long enough for expected claimants, because
-  expired unclaimed rewards can be burned by anyone
+  expired unclaimed rewards can be recycled by anyone
 
 ## For AI Agents
 

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@bananapus/distributor-v6",
-  "version": "0.0.31",
+  "version": "0.0.33",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/Bananapus/nana-distributor-v6"
+    "url": "git+https://github.com/Bananapus/nana-distributor-v6.git"
   },
   "files": [
     "foundry.toml",
@@ -24,8 +24,8 @@
     "deploy:testnets": "source ./.env && npx sphinx propose ./script/Deploy.s.sol --networks testnets"
   },
   "dependencies": {
-    "@bananapus/721-hook-v6": "^0.0.57",
-    "@bananapus/core-v6": "^0.0.68",
+    "@bananapus/721-hook-v6": "^0.0.59",
+    "@bananapus/core-v6": "^0.0.72",
     "@bananapus/permission-ids-v6": "^0.0.27",
     "@openzeppelin/contracts": "5.6.1",
     "@prb/math": "4.1.1",

package/src/JB721Distributor.sol

@@ -29,7 +29,7 @@ import {JBVestingData} from "./structs/JBVestingData.sol";
 /// @dev Any project can use this distributor by configuring a payout split with
 /// `hook = this contract` and `beneficiary = address(their 721 hook)`.
 /// @dev The stake weight of each NFT is its tier's `votingUnits`. Burned NFTs are excluded from the total stake
-/// calculation and their unlocked forfeited rewards can be burned via `releaseForfeitedRewards`.
+/// calculation and their unlocked forfeited rewards can be recycled via `releaseForfeitedRewards`.
 /// @dev Funded rewards are assigned to the funding round. NFT owners claim historical rounds lazily; all unclaimed
 /// past rewards begin vesting when the current NFT owner claims, not when the rewards were funded.
 /// @dev Implements `IJBSplitHook` so it can receive tokens directly from Juicebox project payout splits.
@@ -85,7 +85,7 @@ contract JB721Distributor is JBDistributor, IJB721Distributor {
     //*********************************************************************//
 
     /// @param directory The JB directory used to verify terminal/controller callers.
-    /// @param controller The JB controller used to burn forfeited project-token rewards.
+    /// @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.
     /// @param revOwner The REVOwner contract that must own revnet reward token projects.
     /// @param initialRoundDuration The duration of each round, specified in seconds.
@@ -697,14 +697,11 @@ contract JB721Distributor is JBDistributor, IJB721Distributor {
         // Skip already-vested tokenIds — check if the last vesting entry targets the same release round.
         {
             // Load the number of existing vesting entries for this token.
-            uint256 numVesting = vestingDataOf[ctx.hook][tokenId][ctx.token].length;
+            JBVestingData[] storage vestings = vestingDataOf[ctx.hook][tokenId][ctx.token];
+            uint256 numVesting = vestings.length;
 
             // If at least one entry exists and its release round matches, this token was already vested this round.
-            if (
-                numVesting != 0
-                    && vestingDataOf[ctx.hook][tokenId][ctx.token][numVesting - 1].releaseRound
-                        == ctx.vestingReleaseRound
-            ) {
+            if (numVesting != 0 && vestings[numVesting - 1].releaseRound == ctx.vestingReleaseRound) {
                 return (0, newUniqueCount);
             }
         }

package/src/JBDistributor.sol

@@ -95,9 +95,6 @@ abstract contract JBDistributor is IJBDistributor {
     /// @notice Thrown when vesting loans are requested from a distributor with no vesting period.
     error JBDistributor_VestingLoansDisabled();
 
-    /// @notice Thrown when rewards cannot be burned by the JB controller.
-    error JBDistributor_TokenNotBurnable(address token);
-
     /// @notice Thrown when a value cannot fit in a uint208 reward-round field.
     error JBDistributor_Uint208Overflow(uint256 value);
 
@@ -126,7 +123,7 @@ abstract contract JBDistributor is IJBDistributor {
     /// @dev A zero duration means reward rounds do not expire.
     uint48 public immutable override CLAIM_DURATION;
 
-    /// @notice The JB controller used to burn forfeited project-token rewards.
+    /// @notice The JB controller used for token registry lookups and revnet loan permissions.
     IJBController public immutable override CONTROLLER;
 
     /// @notice The duration of each round, specified in seconds.
@@ -231,7 +228,7 @@ abstract contract JBDistributor is IJBDistributor {
     // -------------------------- constructor ---------------------------- //
     //*********************************************************************//
 
-    /// @param controller The JB controller used to burn forfeited project-token rewards.
+    /// @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.
     /// @param revOwner The REVOwner contract that must own revnet reward token projects.
     /// @param initialRoundDuration The duration of each round, specified in seconds.
@@ -389,13 +386,12 @@ abstract contract JBDistributor is IJBDistributor {
         _ensureSnapshotBlock(currentRound());
     }
 
-    /// @notice Burn unlocked rewards tied to burned tokens. When an NFT is burned, its pending vesting entries become
-    /// stranded — this function unlocks and burns them instead of sending them to the beneficiary. Anyone can call
-    /// this for burned tokens.
+    /// @notice Recycle unlocked rewards tied to burned tokens into the current reward round.
+    /// @dev Anyone can call this for burned tokens.
     /// @param hook The hook whose tokens were burned.
     /// @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 are burned. Kept for interface compatibility.
+    /// @param tokens The reward tokens to recycle.
+    /// @param beneficiary Unused for forfeiture. Kept for interface compatibility.
     function releaseForfeitedRewards(
         address hook,
         uint256[] calldata tokenIds,
@@ -408,7 +404,7 @@ abstract contract JBDistributor is IJBDistributor {
         // Do not let reward-token callbacks mutate vesting state during inbound balance-delta accounting.
         _requireNotAcceptingToken();
 
-        // Make sure that all tokens are burned.
+        // Make sure that all staker token IDs are burned.
         for (uint256 i; i < tokenIds.length;) {
             if (!_tokenBurned({hook: hook, tokenId: tokenIds[i]})) {
                 revert JBDistributor_NoAccess({hook: hook, tokenId: tokenIds[i], account: msg.sender});
@@ -418,7 +414,7 @@ abstract contract JBDistributor is IJBDistributor {
             }
         }
 
-        // Unlock the rewards and burn the forfeited amount.
+        // Unlock the rewards and recycle the forfeited amount.
         _unlockRewards({hook: hook, tokenIds: tokenIds, tokens: tokens, beneficiary: beneficiary, ownerClaim: false});
     }
 
@@ -477,14 +473,15 @@ abstract contract JBDistributor is IJBDistributor {
         // Keep a reference to the latest vested index.
         uint256 vestedIndex = latestVestedIndexOf[hook][tokenId][token];
 
-        // Keep a reference to the number of vesting rounds for the tokenId and token.
-        uint256 numberOfVestingRounds = vestingDataOf[hook][tokenId][token].length;
+        // Keep a reference to the vesting data array.
+        JBVestingData[] storage vestings = vestingDataOf[hook][tokenId][token];
+        uint256 numberOfVestingRounds = vestings.length;
 
         while (vestedIndex < numberOfVestingRounds) {
             uint256 lockedShare;
 
             // Keep a reference to the vested data being iterated on.
-            JBVestingData memory vesting = vestingDataOf[hook][tokenId][token][vestedIndex];
+            JBVestingData memory vesting = vestings[vestedIndex];
 
             lockedShare = JBVestingMath.lockedShareOf({
                 releaseRound: vesting.releaseRound,
@@ -1210,33 +1207,6 @@ abstract contract JBDistributor is IJBDistributor {
         });
     }
 
-    /// @notice Burn reward inventory using the JB controller.
-    /// @param hook The hook whose tracked balance is being burned.
-    /// @param token The reward token to burn.
-    /// @param amount The amount to burn.
-    function _burnRewardTokens(address hook, IERC20 token, uint256 amount) internal {
-        // No-op zero burns so callers can batch empty or already-settled rounds safely.
-        if (amount == 0) return;
-
-        // A missing controller means there is no burn authority for any reward token.
-        if (address(CONTROLLER) == address(0)) revert JBDistributor_TokenNotBurnable({token: address(token)});
-
-        // Only JB project tokens can be burned through `JBController.burnTokensOf`.
-        uint256 projectId = CONTROLLER.TOKENS().projectIdOf({token: IJBToken(address(token))});
-
-        // Revert instead of sending unsupported rewards to a burn address.
-        if (projectId == 0) revert JBDistributor_TokenNotBurnable({token: address(token)});
-
-        // Remove the burned amount from the hook's reward inventory.
-        _balanceOf[hook][token] -= amount;
-
-        // Remove the same amount from the global inventory tracked for this token.
-        _accountedBalanceOf[token] -= amount;
-
-        // Burn from this distributor's project-token balance or token credits.
-        CONTROLLER.burnTokensOf({holder: address(this), projectId: projectId, tokenCount: amount, memo: ""});
-    }
-
     /// @notice Resolve the revnet project ID for a reward token.
     /// @param token The reward token to resolve.
     /// @return revnetId The token's revnet project ID.
@@ -1397,8 +1367,11 @@ abstract contract JBDistributor is IJBDistributor {
                         token.safeTransfer({to: beneficiary, value: totalTokenAmount});
                     }
                 } else {
-                    // If forfeiture: remove the unlocked amount from inventory and burn it through the JB controller.
-                    _burnRewardTokens({hook: hook, token: token, amount: totalTokenAmount});
+                    // If forfeiture: keep inventory in the distributor and give the current staker set a fresh round.
+                    _recordRewardRound({hook: hook, token: token, amount: totalTokenAmount});
+                    emit ForfeitedRewardsRecycled({
+                        hook: hook, round: round, token: token, amount: totalTokenAmount, caller: msg.sender
+                    });
                 }
             }
 
@@ -1594,12 +1567,13 @@ abstract contract JBDistributor is IJBDistributor {
         // Keep a reference to the latest fully vested index.
         uint256 vestedIndex = latestVestedIndexOf[hook][tokenId][token];
 
-        // Keep a reference to the number of vesting entries for the token ID and token.
-        uint256 numberOfVestingRounds = vestingDataOf[hook][tokenId][token].length;
+        // Keep a reference to the vesting data array.
+        JBVestingData[] storage vestings = vestingDataOf[hook][tokenId][token];
+        uint256 numberOfVestingRounds = vestings.length;
 
         while (vestedIndex < numberOfVestingRounds) {
             // Keep a reference to the vested data being iterated on.
-            JBVestingData memory vesting = vestingDataOf[hook][tokenId][token][vestedIndex];
+            JBVestingData memory vesting = vestings[vestedIndex];
 
             // Use `original - alreadyPaid` to include rounding dust in the remaining amount.
             tokenAmount += JBVestingMath.unclaimedAmountOf({
@@ -1641,8 +1615,8 @@ abstract contract JBDistributor is IJBDistributor {
         }
     }
 
-    /// @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`.
+    /// @notice Check whether a staker token has been burned. Burned tokens are excluded from stake calculations,
+    /// and their unlocked forfeited rewards can be recycled via `releaseForfeitedRewards`.
     /// @param hook The hook the token belongs to.
     /// @param tokenId The token ID to check.
     /// @return tokenWasBurned True if the token has been burned.

package/src/JBTokenDistributor.sol

@@ -69,7 +69,7 @@ contract JBTokenDistributor is JBDistributor, IJBTokenDistributor {
     //*********************************************************************//
 
     /// @param directory The JB directory used to verify terminal/controller callers.
-    /// @param controller The JB controller used to burn forfeited project-token rewards.
+    /// @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.
     /// @param revOwner The REVOwner contract that must own revnet reward token projects.
     /// @param initialRoundDuration The duration of each round, specified in seconds.

package/src/interfaces/IJBDistributor.sol

@@ -97,6 +97,16 @@ interface IJBDistributor {
         address caller
     );
 
+    /// @notice Emitted when unlocked rewards from burned tokens are recycled into the current reward round.
+    /// @param hook The hook whose forfeited rewards were recycled.
+    /// @param round The reward round receiving the recycled rewards.
+    /// @param token The reward token that was recycled.
+    /// @param amount The forfeited reward amount recycled.
+    /// @param caller The address that triggered the recycle.
+    event ForfeitedRewardsRecycled(
+        address indexed hook, uint256 indexed round, IERC20 indexed token, uint256 amount, address caller
+    );
+
     /// @notice Emitted when a liquidated distributor-held Revnet loan is written off.
     /// @param hook The hook whose vesting rewards were collateralized.
     /// @param tokenId The token ID whose vesting rewards were collateralized.
@@ -153,7 +163,7 @@ interface IJBDistributor {
     /// @dev A zero duration means reward rounds do not expire.
     function CLAIM_DURATION() external view returns (uint48);
 
-    /// @notice The JB controller used to burn forfeited project-token rewards.
+    /// @notice The JB controller used for token registry lookups and revnet loan permissions.
     function CONTROLLER() external view returns (IJBController);
 
     /// @notice The duration of each round, specified in seconds.
@@ -307,10 +317,10 @@ interface IJBDistributor {
         payable
         returns (uint256 paidOffLoanId);
 
-    /// @notice Burn unlocked rewards for burned tokens.
+    /// @notice Recycle unlocked rewards from burned tokens into the current reward round.
     /// @param hook The hook whose tokens were burned.
     /// @param tokenIds The IDs of the burned tokens.
-    /// @param tokens The addresses of the tokens to burn.
+    /// @param tokens The reward tokens to recycle.
     /// @param beneficiary Unused for forfeiture.
     function releaseForfeitedRewards(
         address hook,

package/src/structs/JBRewardRoundData.sol

@@ -5,7 +5,7 @@ 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 burned. Zero means no expiration.
+/// @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.
 struct JBRewardRoundData {
     uint208 amount;