@bananapus/distributor-v6 0.0.28 → 0.0.29

package/README.md

@@ -37,11 +37,12 @@ If the issue is "where did the project's value come from?" start in `nana-core-v
 
 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
-3. optional direct funding can set a claim duration; split funding and plain `fund` stay non-expiring
+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
 6. recipients collect their vested share as the configured vesting schedule unlocks
-7. some unclaimable value can be reclaimed through explicit recovery paths, depending on the distributor type
+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
 
 This repo does not explain why an allocation exists. It only defines how funded inventory is handed out.
 
@@ -57,11 +58,21 @@ This repo does not explain why an allocation exists. It only defines how funded
 - 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:
   token rewards are claimed by the encoded staker address, while 721 rewards are claimed by the current NFT owner
-- `fundWithClaimDuration` starts the claim window when the funded round first becomes claimable; incompatible
-  same-round deadlines for the same hook and reward token revert
+- `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
   remain claimable on their normal vesting curve
-- `releaseForfeitedRewards` matters for 721 distributions; token-vote distributions do not have the same burned-token path
+- 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
+- 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
+- if Revnet liquidates a distributor-held vesting loan, anyone can call `writeOffLiquidatedVestingLoan` to clear the
+  stale collection lock and forfeit only the vesting rewards that were collateralized by that loan
+- distributors deployed with `VESTING_ROUNDS == 0` disable revnet vesting loans because rewards are immediately
+  collectible instead of locked in a vesting position
+- `releaseForfeitedRewards` matters for 721 distributions; token-vote distributions do not have the same burned-token
+  forfeiture path
 - snapshot timing is part of the trusted surface
 - this repo settles distributions, but it does not prove the upstream entitlement math was correct
 
@@ -77,6 +88,7 @@ This repo does not explain why an allocation exists. It only defines how funded
 1. `test/JBTokenDistributor.t.sol`
 2. `test/JB721Distributor.t.sol`
 3. `test/invariant/JB721DistributorInvariant.t.sol`
+4. `test/regression/VestingLoanRegression.t.sol`
 
 ## Install
 
@@ -118,8 +130,8 @@ script/
 - 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
 - teams should review claim timing and snapshot assumptions with the same care they review the payout source
-- rewarders that set claim durations should choose a window long enough for expected claimants, because expired
-  unclaimed rewards can be burned by anyone
+- 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
 
 ## For AI Agents
 

package/foundry.toml

@@ -2,6 +2,7 @@
 solc = '0.8.28'
 bytecode_hash = "none"
 evm_version = 'cancun'
+via_ir = true
 optimizer_runs = 200
 libs = ["node_modules", "lib"]
 fs_permissions = [{ access = "read-write", path = "./"}]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/distributor-v6",
-  "version": "0.0.28",
+  "version": "0.0.29",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -28,7 +28,8 @@
     "@bananapus/core-v6": "^0.0.60",
     "@bananapus/permission-ids-v6": "^0.0.27",
     "@openzeppelin/contracts": "5.6.1",
-    "@prb/math": "4.1.1"
+    "@prb/math": "4.1.1",
+    "@rev-net/core-v6": "^0.0.74"
   },
   "devDependencies": {
     "@sphinx-labs/plugins": "0.33.3"

package/script/Deploy.s.sol

@@ -3,7 +3,10 @@ pragma solidity 0.8.28;
 
 import {Script} from "forge-std/Script.sol";
 
+import {IJBController} from "@bananapus/core-v6/src/interfaces/IJBController.sol";
 import {IJBDirectory} from "@bananapus/core-v6/src/interfaces/IJBDirectory.sol";
+import {IREVLoans} from "@rev-net/core-v6/src/interfaces/IREVLoans.sol";
+import {IREVOwner} from "@rev-net/core-v6/src/interfaces/IREVOwner.sol";
 
 import {JB721Distributor} from "../src/JB721Distributor.sol";
 
@@ -13,11 +16,27 @@ contract Deploy is Script {
 
         // Configure these values before deploying.
         IJBDirectory directory = IJBDirectory(vm.envAddress("DIRECTORY_ADDRESS"));
+        IJBController controller = IJBController(vm.envAddress("CONTROLLER_ADDRESS"));
+        IREVLoans revLoans = IREVLoans(vm.envOr("REV_LOANS_ADDRESS", address(0)));
+        IREVOwner revOwner = IREVOwner(vm.envOr("REV_OWNER_ADDRESS", address(0)));
         uint256 roundDuration = vm.envUint("ROUND_DURATION");
         uint256 vestingRounds = vm.envUint("VESTING_ROUNDS");
+        uint256 rawClaimDuration = vm.envUint("CLAIM_DURATION");
+
+        require(rawClaimDuration <= type(uint48).max, "CLAIM_DURATION_TOO_LARGE");
+
+        // Safe because the explicit bound above rejects values larger than uint48.
+        // forge-lint: disable-next-line(unsafe-typecast)
+        uint48 claimDuration = uint48(rawClaimDuration);
 
         new JB721Distributor({
-            directory: directory, initialRoundDuration: roundDuration, initialVestingRounds: vestingRounds
+            directory: directory,
+            controller: controller,
+            revLoans: revLoans,
+            revOwner: revOwner,
+            initialRoundDuration: roundDuration,
+            initialVestingRounds: vestingRounds,
+            initialClaimDuration: claimDuration
         });
 
         vm.stopBroadcast();

package/src/JB721Distributor.sol

@@ -3,6 +3,7 @@ pragma solidity 0.8.28;
 
 import {IJB721Checkpoints} from "@bananapus/721-hook-v6/src/interfaces/IJB721Checkpoints.sol";
 import {IJB721TiersHook} from "@bananapus/721-hook-v6/src/interfaces/IJB721TiersHook.sol";
+import {IJBController} from "@bananapus/core-v6/src/interfaces/IJBController.sol";
 import {IJBDirectory} from "@bananapus/core-v6/src/interfaces/IJBDirectory.sol";
 import {IJBSplitHook} from "@bananapus/core-v6/src/interfaces/IJBSplitHook.sol";
 import {IJBTerminal} from "@bananapus/core-v6/src/interfaces/IJBTerminal.sol";
@@ -13,6 +14,8 @@ import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
 import {IERC721} from "@openzeppelin/contracts/token/ERC721/IERC721.sol";
 import {IERC165} from "@openzeppelin/contracts/utils/introspection/IERC165.sol";
 import {mulDiv} from "@prb/math/src/Common.sol";
+import {IREVLoans} from "@rev-net/core-v6/src/interfaces/IREVLoans.sol";
+import {IREVOwner} from "@rev-net/core-v6/src/interfaces/IREVOwner.sol";
 
 import {JBDistributor} from "./JBDistributor.sol";
 import {IJB721Distributor} from "./interfaces/IJB721Distributor.sol";
@@ -26,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 unvested rewards can be reclaimed via `releaseForfeitedRewards`.
+/// calculation and their unlocked forfeited rewards can be burned 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.
@@ -82,14 +85,22 @@ contract JB721Distributor is JBDistributor, IJB721Distributor {
     //*********************************************************************//
 
     /// @param directory The JB directory used to verify terminal/controller callers.
+    /// @param controller The JB controller used to burn expired or forfeited project-token rewards.
+    /// @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.
     /// @param initialVestingRounds The number of rounds until tokens are fully vested.
+    /// @param initialClaimDuration The number of seconds claimants have after each reward round becomes claimable.
     constructor(
         IJBDirectory directory,
+        IJBController controller,
+        IREVLoans revLoans,
+        IREVOwner revOwner,
         uint256 initialRoundDuration,
-        uint256 initialVestingRounds
+        uint256 initialVestingRounds,
+        uint48 initialClaimDuration
     )
-        JBDistributor(initialRoundDuration, initialVestingRounds)
+        JBDistributor(controller, revLoans, revOwner, initialRoundDuration, initialVestingRounds, initialClaimDuration)
     {
         DIRECTORY = directory;
     }
@@ -129,7 +140,7 @@ contract JB721Distributor is JBDistributor, IJB721Distributor {
 
             if (msg.value != 0) {
                 // Assign native split proceeds to the current reward round for this 721 hook.
-                _recordRewardFunding({hook: hook, token: IERC20(context.token), amount: msg.value, claimDuration: 0});
+                _recordRewardFunding({hook: hook, token: IERC20(context.token), amount: msg.value});
             }
         } else {
             // Validate that native ETH is not cross-booked under an ERC-20 token.
@@ -147,7 +158,7 @@ contract JB721Distributor is JBDistributor, IJB721Distributor {
                 _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, claimDuration: 0});
+            _recordRewardFunding({hook: hook, token: IERC20(context.token), amount: delta});
         }
     }
 
@@ -223,14 +234,14 @@ contract JB721Distributor is JBDistributor, IJB721Distributor {
     /// @param hook The 721 hook whose NFT owners are claiming.
     /// @param tokenIds The NFT token IDs to claim for.
     /// @param tokens The reward tokens to claim.
-    function _claimPastRewards(address hook, uint256[] calldata tokenIds, IERC20[] calldata tokens) internal {
+    function _claimPastRewards(address hook, 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 + vestingRounds});
+            JBClaimContext({hook: hook, 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;) {
@@ -546,7 +557,7 @@ contract JB721Distributor is JBDistributor, IJB721Distributor {
     /// @notice Revert unless the caller is authorized to claim each NFT token ID.
     /// @param hook The 721 hook whose NFT owners are claiming.
     /// @param tokenIds The NFT token IDs to check.
-    function _requireCanClaimTokenIds(address hook, uint256[] calldata tokenIds) internal view {
+    function _requireCanClaimTokenIds(address hook, uint256[] calldata tokenIds) internal view override {
         // Each requested NFT must currently belong to msg.sender and appear in strictly increasing order.
         for (uint256 i; i < tokenIds.length;) {
             uint256 tokenId = tokenIds[i];