@bananapus/distributor-v6 0.0.3 → 0.0.5

package/.github/pull_request_template.md

@@ -13,7 +13,7 @@ What new trust boundary, failure mode, operational dependency, or integration ca
 - [ ] Updated `/v6/evm/RISKS.md` because ecosystem behavior changed
 - [ ] If no `RISKS.md` update was needed, I explained why in this PR
 
-Reference: [`/v6/evm/docs/RISKS_MAINTENANCE.md`](../docs/RISKS_MAINTENANCE.md)
+Reference: [`/v6/evm/RISKS_MAINTENANCE.md`](../../RISKS_MAINTENANCE.md)
 
 ## Checklist
 

package/.github/workflows/test.yml

@@ -22,5 +22,7 @@ jobs:
         uses: foundry-rs/foundry-toolchain@v1
       - name: Run tests
         run: forge test --fail-fast --summary --detailed --skip "*/script/**"
+        env:
+          RPC_ETHEREUM_MAINNET: ${{ secrets.RPC_ETHEREUM_MAINNET }}
       - name: Check contract sizes
         run: forge build --sizes --skip "*/test/**" --skip "*/script/**" --skip SphinxUtils

package/USER_JOURNEYS.md

@@ -55,6 +55,8 @@ This repo distributes already-owned assets over time. It snapshots stake, starts
 2. The distributor snapshots the relevant balance and stake source.
 3. Vesting entries become claimable over the configured schedule.
 
+**Snapshot timing:** The snapshot for each round is taken when the previous round first sees activity (`poke`, `beginVesting`, or `collectVestedRewards`). To be included in round N's distribution, make sure your tokens are held and delegated before anyone interacts with round N-1. In practice, keep your delegation current — if it is set before the previous round's activity begins, your voting power will be counted for the next round.
+
 **Failure Modes**
 - zero total stake
 - bad deployment parameters such as zero round duration or zero vesting rounds

package/foundry.lock

@@ -0,0 +1,5 @@
+{
+  "lib/forge-std": {
+    "rev": "f494b0c2c045dda3df3d761bc82209b9a015c4e7"
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/distributor-v6",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -17,9 +17,9 @@
     "deploy:testnets": "source ./.env && npx sphinx propose ./script/Deploy.s.sol --networks testnets"
   },
   "dependencies": {
-    "@bananapus/721-hook-v6": "^0.0.36",
-    "@bananapus/core-v6": "^0.0.34",
-    "@bananapus/permission-ids-v6": "^0.0.17",
+    "@bananapus/721-hook-v6": "^0.0.38",
+    "@bananapus/core-v6": "^0.0.36",
+    "@bananapus/permission-ids-v6": "^0.0.19",
     "@openzeppelin/contracts": "^5.6.1",
     "@prb/math": "^4.1.0"
   },

package/src/JB721Distributor.sol

@@ -13,8 +13,11 @@ import {IERC165} from "@openzeppelin/contracts/utils/introspection/IERC165.sol";
 import {IERC721} from "@openzeppelin/contracts/token/ERC721/IERC721.sol";
 import {IVotes} from "@openzeppelin/contracts/governance/utils/IVotes.sol";
 
+import {mulDiv} from "@prb/math/src/Common.sol";
+
 import {IJB721Distributor} from "./interfaces/IJB721Distributor.sol";
 import {JBDistributor} from "./JBDistributor.sol";
+import {JBVestingData} from "./structs/JBVestingData.sol";
 
 /// @notice A singleton distributor that distributes ERC-20 rewards to JB 721 NFT stakers with linear vesting.
 /// @dev Any project can use this distributor by configuring a payout split with
@@ -32,6 +35,19 @@ contract JB721Distributor is JBDistributor, IJB721Distributor {
     /// @notice Thrown when the caller is not a terminal or controller for the project.
     error JB721Distributor_Unauthorized();
 
+    //*********************************************************************//
+    // ----------------------------- structs ----------------------------- //
+    //*********************************************************************//
+
+    /// @dev Bundles per-round vesting parameters to avoid stack-too-deep.
+    struct VestContext {
+        address hook;
+        IERC20 token;
+        uint256 distributable;
+        uint256 totalStakeAmount;
+        uint256 vestingReleaseRound;
+    }
+
     //*********************************************************************//
     // ---------------- public immutable stored properties --------------- //
     //*********************************************************************//
@@ -44,7 +60,7 @@ contract JB721Distributor is JBDistributor, IJB721Distributor {
     //*********************************************************************//
 
     /// @param directory The JB directory used to verify terminal/controller callers.
-    /// @param roundDuration_ The minimum amount of time stakers have to claim rewards, specified in blocks.
+    /// @param roundDuration_ The duration of each round, specified in seconds.
     /// @param vestingRounds_ The number of rounds until tokens are fully vested.
     constructor(
         IJBDirectory directory,
@@ -84,18 +100,21 @@ contract JB721Distributor is JBDistributor, IJB721Distributor {
         // The target hook is the split's beneficiary.
         address hook = address(context.split.beneficiary);
 
-        // If it's not a native-token transfer, check if the caller approved tokens (terminal pattern).
+        // If it's not a native-token transfer, credit the ERC-20 amount.
         if (msg.value == 0 && context.amount != 0) {
-            uint256 balanceBefore = IERC20(context.token).balanceOf(address(this));
-            // Check if the caller has granted an allowance (terminal). If so, pull the tokens.
-            // The controller sends tokens before calling, so no pull is needed in that case.
             uint256 allowance = IERC20(context.token).allowance(msg.sender, address(this));
             if (allowance >= context.amount) {
-                // Terminal pattern: pull tokens via transferFrom.
+                // Terminal path: the caller granted an allowance — pull tokens via transferFrom.
+                // Use balance delta to handle fee-on-transfer tokens correctly.
+                uint256 balanceBefore = IERC20(context.token).balanceOf(address(this));
                 IERC20(context.token).safeTransferFrom(msg.sender, address(this), context.amount);
+                _balanceOf[hook][IERC20(context.token)] += IERC20(context.token).balanceOf(address(this))
+                - balanceBefore;
+            } else {
+                // Controller-prepaid path: the controller sends tokens directly before calling processSplitWith.
+                // Credit the declared amount since the tokens are already held by this contract.
+                _balanceOf[hook][IERC20(context.token)] += context.amount;
             }
-            // For both terminal and controller paths, credit actual received amount (handles fee-on-transfer).
-            _balanceOf[hook][IERC20(context.token)] += IERC20(context.token).balanceOf(address(this)) - balanceBefore;
         } else if (msg.value != 0) {
             // Native ETH: credit actual value received.
             _balanceOf[hook][IERC20(context.token)] += msg.value;
@@ -118,6 +137,69 @@ contract JB721Distributor is JBDistributor, IJB721Distributor {
     // ---------------------- internal transactions ---------------------- //
     //*********************************************************************//
 
+    /// @notice Override vesting to cap each owner's consumed voting power across all their NFTs.
+    /// @dev Prevents an owner with N NFTs of V voting units each from claiming N*V when their pastVotes < N*V.
+    ///      Iterates over all token IDs in the batch, delegating per-token logic to `_vestSingleToken`. A pair of
+    ///      scratch arrays (`owners` and `consumed`) tracks how much voting power each distinct owner has used so far,
+    ///      ensuring the aggregate claim never exceeds the owner's snapshot voting power.
+    ///      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 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.
+    /// @return totalVestingAmount The sum of reward tokens that began vesting across all processed token IDs.
+    function _vestTokenIds(
+        address hook,
+        uint256[] calldata tokenIds,
+        IERC20 token,
+        uint256 distributable,
+        uint256 totalStakeAmount,
+        uint256 vestingReleaseRound
+    )
+        internal
+        override
+        returns (uint256 totalVestingAmount)
+    {
+        // Bundle iteration-constant parameters into a struct to avoid stack-too-deep errors.
+        VestContext memory ctx = VestContext({
+            hook: hook,
+            token: token,
+            distributable: distributable,
+            totalStakeAmount: totalStakeAmount,
+            vestingReleaseRound: vestingReleaseRound
+        });
+
+        // Allocate scratch arrays sized to the maximum possible number of distinct owners (one per token ID).
+        address[] memory owners = new address[](tokenIds.length);
+        uint256[] memory consumed = new uint256[](tokenIds.length);
+
+        // Track how many distinct owners have been recorded in the scratch arrays so far.
+        uint256 uniqueCount;
+
+        // Iterate over every token ID in the batch.
+        for (uint256 j; j < tokenIds.length;) {
+            // Vest the single token, receiving its reward amount and the updated distinct owner count.
+            (uint256 tokenAmount, uint256 newUniqueCount) = _vestSingleToken({
+                ctx: ctx, tokenId: tokenIds[j], owners: owners, consumed: consumed, uniqueCount: uniqueCount
+            });
+
+            // Carry the updated owner count forward so subsequent tokens can reference the same tracking data.
+            uniqueCount = newUniqueCount;
+
+            unchecked {
+                // Accumulate the individual token's reward into the batch-wide total.
+                totalVestingAmount += tokenAmount;
+                ++j;
+            }
+        }
+    }
+
+    //*********************************************************************//
+    // ----------------------- internal views ---------------------------- //
+    //*********************************************************************//
+
     /// @notice Check if the account owns the given NFT token ID.
     /// @param hook The hook the token belongs to.
     /// @param tokenId The ID of the token to check.
@@ -127,22 +209,40 @@ contract JB721Distributor is JBDistributor, IJB721Distributor {
         canClaim = IERC721(hook).ownerOf(tokenId) == account;
     }
 
+    /// @notice Checks if the given token was burned.
+    /// @param hook The hook the token belongs to.
+    /// @param tokenId The tokenId to check.
+    /// @return tokenWasBurned True if the token was burned.
+    function _tokenBurned(address hook, uint256 tokenId) internal view override returns (bool tokenWasBurned) {
+        // slither-disable-next-line unused-return
+        try IERC721(hook).ownerOf(tokenId) returns (address) {
+            tokenWasBurned = false;
+        } catch {
+            tokenWasBurned = true;
+        }
+    }
+
     /// @notice The stake weight of a given NFT token ID based on its tier's voting units, validated against historical
     /// state.
-    /// @dev Returns 0 if the token's current owner had no checkpointed voting power at the round's start block,
+    /// @dev Returns 0 if the token's current owner had no checkpointed voting power at the round's snapshot block,
     /// preventing late mints from capturing pro-rata rewards within the current round.
     /// @param hook The hook the token belongs to.
     /// @param tokenId The ID of the token to get the stake weight of.
     /// @return tokenStakeAmount The voting units of the token's tier (or 0 if ineligible).
     function _tokenStake(address hook, uint256 tokenId) internal view override returns (uint256 tokenStakeAmount) {
-        uint256 votingUnits = IJB721TiersHook(hook).STORE().tierOfTokenId(hook, tokenId, false).votingUnits;
+        uint256 votingUnits =
+            IJB721TiersHook(hook)
+        .STORE()
+        .tierOfTokenId({hook: hook, tokenId: tokenId, includeResolvedUri: false})
+        .votingUnits;
 
-        // Use the checkpoints module to verify the token's owner had voting power at the round's start block.
+        // Use the checkpoints module to verify the token's owner had voting power at the round's snapshot block.
         // If they had no voting power at that time, this token was minted or acquired after the round started
         // and is not eligible for this round's rewards.
         IJB721Checkpoints checkpoints = IJB721TiersHook(hook).CHECKPOINTS();
         address owner = IERC721(hook).ownerOf(tokenId);
-        uint256 pastVotes = IVotes(address(checkpoints)).getPastVotes(owner, roundStartBlock(currentRound()));
+        uint256 pastVotes =
+            IVotes(address(checkpoints)).getPastVotes({account: owner, timepoint: roundSnapshotBlock[currentRound()]});
 
         // If the owner had no voting power at round start, the token is ineligible.
         // slither-disable-next-line incorrect-equality
@@ -165,16 +265,130 @@ contract JB721Distributor is JBDistributor, IJB721Distributor {
         total = IVotes(address(checkpoints)).getPastTotalSupply(blockNumber);
     }
 
-    /// @notice Checks if the given token was burned.
-    /// @param hook The hook the token belongs to.
-    /// @param tokenId The tokenId to check.
-    /// @return tokenWasBurned True if the token was burned.
-    function _tokenBurned(address hook, uint256 tokenId) internal view override returns (bool tokenWasBurned) {
-        // slither-disable-next-line unused-return
-        try IERC721(hook).ownerOf(tokenId) returns (address) {
-            tokenWasBurned = false;
-        } catch {
-            tokenWasBurned = true;
+    //*********************************************************************//
+    // ----------------------- private helpers --------------------------- //
+    //*********************************************************************//
+
+    /// @notice Vest a single NFT token, enforcing a per-owner voting power cap across the batch.
+    /// @dev Returns 0 for burned tokens, already-vested tokens, tokens whose owner had no snapshot voting power,
+    ///      and tokens whose owner has already exhausted their voting power cap within this batch.
+    ///      The `owners` and `consumed` arrays form a compact map that tracks how much voting power each unique
+    ///      owner has consumed so far. `uniqueCount` tracks how many slots are used.
+    /// @param ctx The vesting context containing hook address, reward token, distributable amount, total stake,
+    ///        and release round.
+    /// @param tokenId The NFT token ID to process.
+    /// @param owners A scratch array mapping slot indices to owner addresses for deduplication within this batch.
+    /// @param consumed A scratch array tracking how much voting power each owner (by slot index) has consumed.
+    /// @param uniqueCount The number of distinct owners seen so far in the batch.
+    /// @return tokenAmount The reward amount vested for this token ID (0 if skipped).
+    /// @return newUniqueCount The updated count of distinct owners after processing this token ID.
+    // slither-disable-next-line incorrect-equality
+    function _vestSingleToken(
+        VestContext memory ctx,
+        uint256 tokenId,
+        address[] memory owners,
+        uint256[] memory consumed,
+        uint256 uniqueCount
+    )
+        private
+        returns (uint256 tokenAmount, uint256 newUniqueCount)
+    {
+        // Initialize the return value to the current count of distinct owners.
+        newUniqueCount = uniqueCount;
+
+        // Skip burned tokens — they are excluded from _totalStake, so including them would overbook vesting.
+        if (_tokenBurned({hook: ctx.hook, tokenId: tokenId})) return (0, newUniqueCount);
+
+        // 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;
+
+            // 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
+            ) {
+                return (0, newUniqueCount);
+            }
+        }
+
+        // Look up the NFT's voting units from its tier in the hook's store.
+        uint256 votingUnits =
+            IJB721TiersHook(ctx.hook)
+        .STORE()
+        .tierOfTokenId({hook: ctx.hook, tokenId: tokenId, includeResolvedUri: false})
+        .votingUnits;
+
+        // Look up the owner, verify snapshot eligibility, and find or create the owner's tracking slot.
+        uint256 ownerIndex;
+        uint256 pastVotes;
+        {
+            // Get the current owner of the NFT.
+            address owner = IERC721(ctx.hook).ownerOf(tokenId);
+
+            // Query the owner's checkpointed voting power at the round's snapshot block.
+            pastVotes = IVotes(address(IJB721TiersHook(ctx.hook).CHECKPOINTS()))
+                .getPastVotes({account: owner, timepoint: roundSnapshotBlock[currentRound()]});
+
+            // If the owner had no voting power at round start, the token is ineligible for this round.
+            // slither-disable-next-line incorrect-equality
+            if (pastVotes == 0) return (0, newUniqueCount);
+
+            // Search the owners array for an existing slot belonging to this owner.
+            bool found;
+            for (uint256 k; k < newUniqueCount;) {
+                if (owners[k] == owner) {
+                    // Re-use the existing tracking slot for this owner.
+                    ownerIndex = k;
+                    found = true;
+                    break;
+                }
+                unchecked {
+                    ++k;
+                }
+            }
+
+            // If no existing slot was found, allocate a new one at the end of the arrays.
+            if (!found) {
+                ownerIndex = newUniqueCount;
+                owners[newUniqueCount] = owner;
+                unchecked {
+                    ++newUniqueCount;
+                }
+            }
+        }
+
+        // Cap this NFT's effective stake at the owner's remaining voting power budget for this batch.
+        uint256 stake;
+        {
+            // Calculate how much voting power the owner has left after prior tokens in this batch.
+            uint256 remaining = pastVotes > consumed[ownerIndex] ? pastVotes - consumed[ownerIndex] : 0;
+
+            // The effective stake is the lesser of the NFT's voting units and the owner's remaining budget.
+            stake = votingUnits < remaining ? votingUnits : remaining;
+        }
+
+        // Record that this owner has consumed additional voting power from their budget.
+        consumed[ownerIndex] += stake;
+
+        // If the effective stake is zero, the owner's budget is exhausted — skip this token.
+        // slither-disable-next-line incorrect-equality
+        if (stake == 0) return (0, newUniqueCount);
+
+        // Calculate the pro-rata reward amount: (distributable * stake) / totalStakeAmount.
+        tokenAmount = mulDiv({x: ctx.distributable, y: stake, denominator: ctx.totalStakeAmount});
+
+        // Only create a vesting entry and emit an event if there is a non-zero reward.
+        if (tokenAmount > 0) {
+            // Push a new vesting data entry for this token ID, starting with zero shareClaimed.
+            vestingDataOf[ctx.hook][tokenId][ctx.token].push(
+                JBVestingData({releaseRound: ctx.vestingReleaseRound, amount: tokenAmount, shareClaimed: 0})
+            );
+
+            // Emit the claim event for off-chain indexers.
+            emit Claimed(ctx.hook, tokenId, ctx.token, tokenAmount, ctx.vestingReleaseRound);
         }
     }
 }