@bananapus/distributor-v6 0.0.11 → 0.0.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/distributor-v6",
-  "version": "0.0.11",
+  "version": "0.0.13",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -26,8 +26,8 @@
     "deploy:testnets": "source ./.env && npx sphinx propose ./script/Deploy.s.sol --networks testnets"
   },
   "dependencies": {
-    "@bananapus/721-hook-v6": "0.0.43",
-    "@bananapus/core-v6": "0.0.39",
+    "@bananapus/721-hook-v6": "0.0.47",
+    "@bananapus/core-v6": "0.0.43",
     "@bananapus/permission-ids-v6": "0.0.22",
     "@openzeppelin/contracts": "5.6.1",
     "@prb/math": "4.1.1"

package/references/operations.md

@@ -7,7 +7,7 @@
 | `JBDistributor` vesting math | Claim totals, `totalVestingAmountOf`, and pool balances still reconcile across rounds |
 | `JBTokenDistributor` checkpoint logic | `getPastVotes` and `getPastTotalSupply` are read at the intended round-start block |
 | `JB721Distributor` stake math | Minted, remaining, and burned supply still produce the intended tier-weighted total stake |
-| `processSplitWith` | Terminal allowance flow and controller pre-funding flow both preserve actual received balances |
+| `processSplitWith` | Allowance-based `transferFrom` flow preserves actual received balances |
 | Deployment inputs | `DIRECTORY_ADDRESS`, `ROUND_DURATION`, and `VESTING_ROUNDS` match the intended chain and operator plan |
 
 ## Common failure modes
@@ -17,7 +17,7 @@
 | A holder gets no rewards in the token distributor | They never delegated, so `getPastVotes` returned zero |
 | Rewards appear stuck in the distributor | Supply was undelegated, vesting never began for the target token IDs, or the round boundary assumption is wrong |
 | 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 path was misclassified between allowance-pull and pre-funded controller flow |
+| Split-hook funding credits the wrong amount | The caller did not grant a sufficient ERC-20 allowance before calling `processSplitWith` |
 
 ## Read Next
 

package/references/runtime.md

@@ -14,14 +14,9 @@
 
 The token distributor depends on checkpointed voting power at the round start block. Holders must delegate for `getPastVotes` to count them, and undelegated supply can leave rewards stranded in the pool for later rounds.
 
-### Funding path split
+### Funding path
 
-`processSplitWith` supports two funding patterns:
-
-- Terminal path: pull tokens via allowance and credit the actual received amount.
-- Controller path: assume tokens were transferred before the hook call and credit `context.amount`.
-
-Mixing these assumptions causes under- or over-accounting.
+`processSplitWith` uses a single funding pattern: the caller grants an ERC-20 allowance and `processSplitWith` pulls tokens via `transferFrom`, crediting the actual received amount.
 
 ### 721 burned-token behavior
 

package/src/JB721Distributor.sol

@@ -34,10 +34,10 @@ contract JB721Distributor is JBDistributor, IJB721Distributor {
     //*********************************************************************//
 
     /// @notice Thrown when native ETH is sent but context.token is not NATIVE_TOKEN.
-    error JB721Distributor_TokenMismatch();
+    error JB721Distributor_TokenMismatch(address token, address expectedToken, uint256 msgValue);
 
     /// @notice Thrown when the caller is not a terminal or controller for the project.
-    error JB721Distributor_Unauthorized();
+    error JB721Distributor_Unauthorized(uint256 projectId, address caller);
 
     //*********************************************************************//
     // ----------------------------- structs ----------------------------- //
@@ -103,8 +103,7 @@ contract JB721Distributor is JBDistributor, IJB721Distributor {
     /// @notice Receives tokens from a Juicebox payout split.
     /// @dev Only callable by a terminal or controller for the project in the context.
     /// @dev The hook address is read from `context.split.beneficiary`.
-    /// @dev The terminal grants an ERC-20 allowance before calling — we pull via `transferFrom`.
-    /// The controller sends tokens directly before calling — nothing to pull.
+    /// @dev Both terminals and controllers grant an ERC-20 allowance before calling — we pull via `transferFrom`.
     /// For native ETH, the terminal sends the amount as `msg.value`.
     /// @param context The split hook context from the terminal or controller.
     function processSplitWith(JBSplitHookContext calldata context) external payable override {
@@ -112,33 +111,27 @@ contract JB721Distributor is JBDistributor, IJB721Distributor {
         if (
             !DIRECTORY.isTerminalOf(context.projectId, IJBTerminal(msg.sender))
                 && DIRECTORY.controllerOf(context.projectId) != IERC165(msg.sender)
-        ) revert JB721Distributor_Unauthorized();
+        ) revert JB721Distributor_Unauthorized({projectId: context.projectId, caller: msg.sender});
 
         // The target hook is the split's beneficiary.
         address hook = address(context.split.beneficiary);
 
         // If it's not a native-token transfer, credit the ERC-20 amount.
         if (msg.value == 0 && context.amount != 0) {
-            uint256 allowance = IERC20(context.token).allowance(msg.sender, address(this));
-            if (allowance >= context.amount) {
-                // 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);
-                uint256 delta = IERC20(context.token).balanceOf(address(this)) - balanceBefore;
-                _balanceOf[hook][IERC20(context.token)] += delta;
-                _accountedBalanceOf[IERC20(context.token)] += delta;
-            } else {
-                // Controller-prepaid path: verify actual unaccounted balance covers the declared amount.
-                uint256 actual = IERC20(context.token).balanceOf(address(this));
-                uint256 unaccounted = actual - _accountedBalanceOf[IERC20(context.token)];
-                if (unaccounted < context.amount) revert JBDistributor_UnfundedSplitCredit();
-                _accountedBalanceOf[IERC20(context.token)] += context.amount;
-                _balanceOf[hook][IERC20(context.token)] += context.amount;
-            }
+            // Pull tokens via transferFrom. Both terminals and controllers grant an ERC-20
+            // allowance before calling. Balance delta handles fee-on-transfer tokens correctly.
+            uint256 balanceBefore = IERC20(context.token).balanceOf(address(this));
+            IERC20(context.token).safeTransferFrom({from: msg.sender, to: address(this), value: context.amount});
+            uint256 delta = IERC20(context.token).balanceOf(address(this)) - balanceBefore;
+            _balanceOf[hook][IERC20(context.token)] += delta;
+            _accountedBalanceOf[IERC20(context.token)] += delta;
         } else if (msg.value != 0) {
             // Validate that context.token matches NATIVE_TOKEN to prevent cross-booking attacks.
-            if (context.token != JBConstants.NATIVE_TOKEN) revert JB721Distributor_TokenMismatch();
+            if (context.token != JBConstants.NATIVE_TOKEN) {
+                revert JB721Distributor_TokenMismatch({
+                    token: context.token, expectedToken: JBConstants.NATIVE_TOKEN, msgValue: msg.value
+                });
+            }
             // Native ETH: credit actual value received.
             _balanceOf[hook][IERC20(context.token)] += msg.value;
             _accountedBalanceOf[IERC20(context.token)] += msg.value;
@@ -246,7 +239,6 @@ contract JB721Distributor is JBDistributor, IJB721Distributor {
     /// @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 {
@@ -278,7 +270,6 @@ contract JB721Distributor is JBDistributor, IJB721Distributor {
             .getPastVotes({account: owner, timepoint: snapshotBlock});
 
         // If the owner had no voting power at round start, the token is ineligible.
-        // slither-disable-next-line incorrect-equality
         if (pastVotes == 0) return 0;
 
         // Cap at the token's tier voting units — the owner's past votes may cover multiple tokens,
@@ -344,7 +335,6 @@ contract JB721Distributor is JBDistributor, IJB721Distributor {
     /// @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,
@@ -396,7 +386,6 @@ contract JB721Distributor is JBDistributor, IJB721Distributor {
                 .getPastVotes({account: owner, timepoint: snapshotBlock});
 
             // If the snapshot 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.
@@ -439,7 +428,6 @@ contract JB721Distributor is JBDistributor, IJB721Distributor {
         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.
@@ -453,7 +441,13 @@ contract JB721Distributor is JBDistributor, IJB721Distributor {
             );
 
             // Emit the claim event for off-chain indexers.
-            emit Claimed(ctx.hook, tokenId, ctx.token, tokenAmount, ctx.vestingReleaseRound);
+            emit Claimed({
+                hook: ctx.hook,
+                tokenId: tokenId,
+                token: ctx.token,
+                amount: tokenAmount,
+                vestingReleaseRound: ctx.vestingReleaseRound
+            });
         }
     }
 }

package/src/JBDistributor.sol

@@ -25,25 +25,22 @@ abstract contract JBDistributor is IJBDistributor {
     //*********************************************************************//
 
     /// @notice Thrown when an empty tokenIds array is passed.
-    error JBDistributor_EmptyTokenIds();
+    error JBDistributor_EmptyTokenIds(uint256 tokenIdCount);
 
     /// @notice Thrown when a native ETH transfer fails.
-    error JBDistributor_NativeTransferFailed();
+    error JBDistributor_NativeTransferFailed(address beneficiary, uint256 amount);
 
     /// @notice Thrown when the caller does not have access to the token.
-    error JBDistributor_NoAccess();
+    error JBDistributor_NoAccess(address hook, uint256 tokenId, address account);
 
     /// @notice Thrown when the round duration is zero.
-    error JBDistributor_InvalidRoundDuration();
+    error JBDistributor_InvalidRoundDuration(uint256 roundDuration);
 
     /// @notice Thrown when there is nothing to distribute for a token in the current round.
-    error JBDistributor_NothingToDistribute();
-
-    /// @notice Thrown when a controller-prepaid split credit is not backed by actual token balance.
-    error JBDistributor_UnfundedSplitCredit();
+    error JBDistributor_NothingToDistribute(address hook, address token, uint256 round);
 
     /// @notice Thrown when unexpected native ETH is sent with an ERC-20 operation.
-    error JBDistributor_UnexpectedNativeValue();
+    error JBDistributor_UnexpectedNativeValue(uint256 msgValue, address token);
 
     //*********************************************************************//
     // ------------------------- public constants ------------------------ //
@@ -88,7 +85,6 @@ abstract contract JBDistributor is IJBDistributor {
     /// @custom:param hook The hook the tokenId belongs to.
     /// @custom:param tokenId The ID of the token to which the vests belong.
     /// @custom:param token The address of the token vested.
-    // slither-disable-next-line uninitialized-state
     mapping(address hook => mapping(uint256 tokenId => mapping(IERC20 token => JBVestingData[]))) public vestingDataOf;
 
     //*********************************************************************//
@@ -118,7 +114,7 @@ abstract contract JBDistributor is IJBDistributor {
     /// @param roundDuration_ The duration of each round, specified in seconds.
     /// @param vestingRounds_ The number of rounds until tokens are fully vested.
     constructor(uint256 roundDuration_, uint256 vestingRounds_) {
-        if (roundDuration_ == 0) revert JBDistributor_InvalidRoundDuration();
+        if (roundDuration_ == 0) revert JBDistributor_InvalidRoundDuration({roundDuration: roundDuration_});
         startingTimestamp = block.timestamp;
         roundDuration = roundDuration_;
         vestingRounds = vestingRounds_;
@@ -136,7 +132,7 @@ abstract contract JBDistributor is IJBDistributor {
     /// @param tokens The reward tokens to begin vesting.
     function beginVesting(address hook, uint256[] calldata tokenIds, IERC20[] calldata tokens) external override {
         // Revert if no token IDs are provided.
-        if (tokenIds.length == 0) revert JBDistributor_EmptyTokenIds();
+        if (tokenIds.length == 0) revert JBDistributor_EmptyTokenIds({tokenIdCount: tokenIds.length});
 
         // Keep a reference to the current round.
         uint256 round = currentRound();
@@ -145,10 +141,9 @@ abstract contract JBDistributor is IJBDistributor {
         _ensureSnapshotBlock(round);
 
         // Keep a reference to the total staked amount at the snapshot block.
-        uint256 totalStakeAmount = _totalStake(hook, roundSnapshotBlock[round]);
+        uint256 totalStakeAmount = _totalStake({hook: hook, blockNumber: roundSnapshotBlock[round]});
 
         // Skip vesting when there are no stakers — funds carry over to the next round.
-        // slither-disable-next-line incorrect-equality
         if (totalStakeAmount == 0) return;
 
         // Loop through each token for which vesting is beginning.
@@ -156,15 +151,23 @@ abstract contract JBDistributor is IJBDistributor {
             IERC20 token = tokens[i];
 
             // Take a snapshot of the token balance if it hasn't been taken already.
-            JBTokenSnapshotData memory snapshot = _takeSnapshotOf(hook, token);
+            JBTokenSnapshotData memory snapshot = _takeSnapshotOf({hook: hook, token: token});
             uint256 distributable = snapshot.balance - snapshot.vestingAmount;
 
             // Revert if there is nothing to distribute for this token.
-            if (distributable == 0) revert JBDistributor_NothingToDistribute();
+            if (distributable == 0) {
+                revert JBDistributor_NothingToDistribute({hook: hook, token: address(token), round: round});
+            }
 
             // Vest each token ID and get the total amount vested.
-            uint256 totalVestingAmount =
-                _vestTokenIds(hook, tokenIds, token, distributable, totalStakeAmount, round + vestingRounds);
+            uint256 totalVestingAmount = _vestTokenIds({
+                hook: hook,
+                tokenIds: tokenIds,
+                token: token,
+                distributable: distributable,
+                totalStakeAmount: totalStakeAmount,
+                vestingReleaseRound: round + vestingRounds
+            });
 
             unchecked {
                 // Store the updated total claimed amount now vesting.
@@ -186,7 +189,9 @@ abstract contract JBDistributor is IJBDistributor {
         if (address(token) == JBConstants.NATIVE_TOKEN) {
             amount = msg.value;
         } else {
-            if (msg.value != 0) revert JBDistributor_UnexpectedNativeValue();
+            if (msg.value != 0) {
+                revert JBDistributor_UnexpectedNativeValue({msgValue: msg.value, token: address(token)});
+            }
             // Use balance delta to handle fee-on-transfer tokens correctly.
             uint256 balanceBefore = token.balanceOf(address(this));
             token.safeTransferFrom(msg.sender, address(this), amount);
@@ -220,14 +225,16 @@ abstract contract JBDistributor is IJBDistributor {
     {
         // Make sure that all tokens are burned.
         for (uint256 i; i < tokenIds.length;) {
-            if (!_tokenBurned(hook, tokenIds[i])) revert JBDistributor_NoAccess();
+            if (!_tokenBurned({hook: hook, tokenId: tokenIds[i]})) {
+                revert JBDistributor_NoAccess({hook: hook, tokenId: tokenIds[i], account: msg.sender});
+            }
             unchecked {
                 ++i;
             }
         }
 
         // Unlock the rewards and send them to the beneficiary.
-        _unlockRewards(hook, tokenIds, tokens, beneficiary, false);
+        _unlockRewards({hook: hook, tokenIds: tokenIds, tokens: tokens, beneficiary: beneficiary, ownerClaim: false});
     }
 
     //*********************************************************************//
@@ -267,7 +274,8 @@ abstract contract JBDistributor is IJBDistributor {
             // Keep a reference to the vested data being iterated on.
             JBVestingData memory vesting = vestingDataOf[hook][tokenId][token][vestedIndex];
 
-            tokenAmount += mulDiv(vesting.amount, MAX_SHARE - vesting.shareClaimed, MAX_SHARE);
+            // Use `original - alreadyPaid` to include rounding dust in the remaining amount.
+            tokenAmount += vesting.amount - mulDiv(vesting.amount, vesting.shareClaimed, MAX_SHARE);
 
             unchecked {
                 ++vestedIndex;
@@ -311,7 +319,15 @@ abstract contract JBDistributor is IJBDistributor {
                 lockedShare = (vesting.releaseRound - round) * MAX_SHARE / vestingRounds;
             }
 
-            tokenAmount += mulDiv(vesting.amount, MAX_SHARE - vesting.shareClaimed - lockedShare, MAX_SHARE);
+            if (lockedShare == 0 && vesting.shareClaimed < MAX_SHARE) {
+                // Final unlock: compute remaining as `original - alreadyPaid` to include dust.
+                tokenAmount += vesting.amount - mulDiv(vesting.amount, vesting.shareClaimed, MAX_SHARE);
+            } else {
+                uint256 newShareClaimed = MAX_SHARE - lockedShare;
+                if (newShareClaimed > vesting.shareClaimed) {
+                    tokenAmount += mulDiv(vesting.amount, newShareClaimed - vesting.shareClaimed, MAX_SHARE);
+                }
+            }
 
             unchecked {
                 ++vestedIndex;
@@ -372,11 +388,13 @@ abstract contract JBDistributor is IJBDistributor {
         override
     {
         // Revert if no token IDs are provided.
-        if (tokenIds.length == 0) revert JBDistributor_EmptyTokenIds();
+        if (tokenIds.length == 0) revert JBDistributor_EmptyTokenIds({tokenIdCount: tokenIds.length});
 
         // Make sure that all tokens can be claimed by this sender.
         for (uint256 i; i < tokenIds.length;) {
-            if (!_canClaim(hook, tokenIds[i], msg.sender)) revert JBDistributor_NoAccess();
+            if (!_canClaim({hook: hook, tokenId: tokenIds[i], account: msg.sender})) {
+                revert JBDistributor_NoAccess({hook: hook, tokenId: tokenIds[i], account: msg.sender});
+            }
             unchecked {
                 ++i;
             }
@@ -389,20 +407,26 @@ abstract contract JBDistributor is IJBDistributor {
         _ensureSnapshotBlock(round);
 
         // Keep a reference to the total staked amount at the snapshot block.
-        uint256 totalStakeAmount = _totalStake(hook, roundSnapshotBlock[round]);
+        uint256 totalStakeAmount = _totalStake({hook: hook, blockNumber: roundSnapshotBlock[round]});
 
         // Loop through each token and auto-vest if there's something distributable.
         for (uint256 i; i < tokens.length;) {
             IERC20 token = tokens[i];
 
             // Take a snapshot of the token balance if it hasn't been taken already.
-            JBTokenSnapshotData memory snapshot = _takeSnapshotOf(hook, token);
+            JBTokenSnapshotData memory snapshot = _takeSnapshotOf({hook: hook, token: token});
             uint256 distributable = snapshot.balance - snapshot.vestingAmount;
 
             // Only auto-vest if there's something to distribute and there's stake.
             if (distributable > 0 && totalStakeAmount > 0) {
-                uint256 totalVestingAmount =
-                    _vestTokenIds(hook, tokenIds, token, distributable, totalStakeAmount, round + vestingRounds);
+                uint256 totalVestingAmount = _vestTokenIds({
+                    hook: hook,
+                    tokenIds: tokenIds,
+                    token: token,
+                    distributable: distributable,
+                    totalStakeAmount: totalStakeAmount,
+                    vestingReleaseRound: round + vestingRounds
+                });
 
                 unchecked {
                     totalVestingAmountOf[hook][token] += totalVestingAmount;
@@ -415,7 +439,7 @@ abstract contract JBDistributor is IJBDistributor {
         }
 
         // Unlock the rewards and send them to the beneficiary.
-        _unlockRewards(hook, tokenIds, tokens, beneficiary, true);
+        _unlockRewards({hook: hook, tokenIds: tokenIds, tokens: tokens, beneficiary: beneficiary, ownerClaim: true});
     }
 
     //*********************************************************************//
@@ -426,16 +450,14 @@ abstract contract JBDistributor is IJBDistributor {
     /// @dev Uses `block.number - 1` because `IVotes.getPastVotes` requires a strictly past block.
     /// @param round The round to ensure a snapshot block for.
     function _ensureSnapshotBlock(uint256 round) internal {
-        // slither-disable-next-line incorrect-equality
         if (roundSnapshotBlock[round] == 0) {
             roundSnapshotBlock[round] = block.number - 1;
-            emit RoundSnapshotRecorded(round, block.number - 1);
+            emit RoundSnapshotRecorded({round: round, snapshotBlock: block.number - 1});
         }
         // Eagerly lock the next round's snapshot to prevent first-caller manipulation.
-        // slither-disable-next-line incorrect-equality
         if (roundSnapshotBlock[round + 1] == 0) {
             roundSnapshotBlock[round + 1] = block.number - 1;
-            emit RoundSnapshotRecorded(round + 1, block.number - 1);
+            emit RoundSnapshotRecorded({round: round + 1, snapshotBlock: block.number - 1});
         }
     }
 
@@ -460,7 +482,9 @@ abstract contract JBDistributor is IJBDistributor {
         // Store the snapshot.
         _snapshotAtRoundOf[hook][token][round] = snapshot;
 
-        emit SnapshotCreated(hook, round, token, snapshot.balance, snapshot.vestingAmount);
+        emit SnapshotCreated({
+            hook: hook, round: round, token: token, balance: snapshot.balance, vestingAmount: snapshot.vestingAmount
+        });
     }
 
     /// @notice Unlocks rewards for the given token IDs and tokens, either for collection or forfeiture.
@@ -485,7 +509,7 @@ abstract contract JBDistributor is IJBDistributor {
             IERC20 token = tokens[i];
 
             // Process all token IDs for this reward token.
-            uint256 totalTokenAmount = _unlockTokenIds(hook, tokenIds, token, round);
+            uint256 totalTokenAmount = _unlockTokenIds({hook: hook, tokenIds: tokenIds, token: token, round: round});
 
             // Perform the transfer.
             if (totalTokenAmount != 0) {
@@ -501,9 +525,12 @@ abstract contract JBDistributor is IJBDistributor {
                     _accountedBalanceOf[token] -= totalTokenAmount;
 
                     if (address(token) == JBConstants.NATIVE_TOKEN) {
-                        // slither-disable-next-line arbitrary-send-eth,reentrancy-eth
                         (bool success,) = beneficiary.call{value: totalTokenAmount}("");
-                        if (!success) revert JBDistributor_NativeTransferFailed();
+                        if (!success) {
+                            revert JBDistributor_NativeTransferFailed({
+                                beneficiary: beneficiary, amount: totalTokenAmount
+                            });
+                        }
                     } else {
                         token.safeTransfer(beneficiary, totalTokenAmount);
                     }
@@ -547,32 +574,46 @@ abstract contract JBDistributor is IJBDistributor {
             uint256 newLatestVestedIndex = vestedIndex;
 
             while (vestedIndex < numberOfVestingRounds) {
-                uint256 lockedShare;
-
                 // Keep a reference to the vested data being iterated on.
                 JBVestingData memory vesting = vestings[vestedIndex];
 
                 // Calculate the share amount that is locked.
+                uint256 lockedShare;
                 if (vesting.releaseRound > round) {
                     lockedShare = (vesting.releaseRound - round) * MAX_SHARE / vestingRounds;
                 }
 
-                uint256 claimAmount = mulDiv(vesting.amount, MAX_SHARE - vesting.shareClaimed - lockedShare, MAX_SHARE);
+                uint256 claimAmount;
+
+                if (lockedShare == 0 && vesting.shareClaimed < MAX_SHARE) {
+                    // Final unlock: compute remaining amount as `original - alreadyPaid` to force
+                    // rounding dust out so nothing is stranded in the entry.
+                    claimAmount = vesting.amount - mulDiv(vesting.amount, vesting.shareClaimed, MAX_SHARE);
+                } else if (MAX_SHARE - lockedShare > vesting.shareClaimed) {
+                    claimAmount = mulDiv(vesting.amount, MAX_SHARE - lockedShare - vesting.shareClaimed, MAX_SHARE);
+                }
 
                 if (claimAmount != 0) {
-                    // Only update the claimed share when a nonzero transfer will occur.
-                    // This keeps dust entries unconsumed so future claims can accumulate enough for a nonzero amount.
                     vestings[vestedIndex].shareClaimed = MAX_SHARE - lockedShare;
                     totalTokenAmount += claimAmount;
-                    emit Collected(hook, tokenId, token, claimAmount, vesting.releaseRound);
+                    emit Collected({
+                        hook: hook,
+                        tokenId: tokenId,
+                        token: token,
+                        amount: claimAmount,
+                        vestingReleaseRound: vesting.releaseRound
+                    });
                 }
 
                 unchecked {
                     ++vestedIndex;
 
                     // Only advance the latest-vested index contiguously past fully exhausted entries.
-                    // slither-disable-next-line incorrect-equality
-                    if (lockedShare == 0 && vestedIndex == newLatestVestedIndex + 1) {
+                    // An entry is exhausted only when its entire share has been claimed (lockedShare == 0).
+                    if (
+                        lockedShare == 0 && vestings[vestedIndex - 1].shareClaimed == MAX_SHARE
+                            && vestedIndex == newLatestVestedIndex + 1
+                    ) {
                         ++newLatestVestedIndex;
                     }
                 }
@@ -611,7 +652,7 @@ abstract contract JBDistributor is IJBDistributor {
             uint256 tokenId = tokenIds[j];
 
             // Skip burned tokens — they are excluded from _totalStake, so including them would overbook vesting.
-            if (_tokenBurned(hook, tokenId)) {
+            if (_tokenBurned({hook: hook, tokenId: tokenId})) {
                 unchecked {
                     ++j;
                 }
@@ -623,7 +664,6 @@ abstract contract JBDistributor is IJBDistributor {
 
             // Skip if this token has already been vested for this round (same releaseRound).
             uint256 numVesting = vestings.length;
-            // slither-disable-next-line incorrect-equality
             if (numVesting != 0 && vestings[numVesting - 1].releaseRound == vestingReleaseRound) {
                 unchecked {
                     ++j;
@@ -632,12 +672,18 @@ abstract contract JBDistributor is IJBDistributor {
             }
 
             // Keep a reference to the amount of tokens being claimed.
-            uint256 tokenAmount = mulDiv(distributable, _tokenStake(hook, tokenId), totalStakeAmount);
+            uint256 tokenAmount = mulDiv(distributable, _tokenStake({hook: hook, tokenId: tokenId}), totalStakeAmount);
 
             // Add to the list of vesting data.
             vestings.push(JBVestingData({releaseRound: vestingReleaseRound, amount: tokenAmount, shareClaimed: 0}));
 
-            emit Claimed(hook, tokenId, token, tokenAmount, vestingReleaseRound);
+            emit Claimed({
+                hook: hook,
+                tokenId: tokenId,
+                token: token,
+                amount: tokenAmount,
+                vestingReleaseRound: vestingReleaseRound
+            });
 
             unchecked {
                 totalVestingAmount += tokenAmount;

package/src/JBTokenDistributor.sol

@@ -29,13 +29,13 @@ contract JBTokenDistributor is JBDistributor, IJBTokenDistributor {
     //*********************************************************************//
 
     /// @notice Thrown when a tokenId has non-zero upper bits (above 160), which would alias to the same staker address.
-    error JBTokenDistributor_InvalidTokenId();
+    error JBTokenDistributor_InvalidTokenId(uint256 tokenId);
 
     /// @notice Thrown when native ETH is sent but context.token is not NATIVE_TOKEN.
-    error JBTokenDistributor_TokenMismatch();
+    error JBTokenDistributor_TokenMismatch(address token, address expectedToken, uint256 msgValue);
 
     /// @notice Thrown when the caller is not a terminal or controller for the project.
-    error JBTokenDistributor_Unauthorized();
+    error JBTokenDistributor_Unauthorized(uint256 projectId, address caller);
 
     //*********************************************************************//
     // ---------------- public immutable stored properties --------------- //
@@ -81,33 +81,27 @@ contract JBTokenDistributor is JBDistributor, IJBTokenDistributor {
         if (
             !DIRECTORY.isTerminalOf(context.projectId, IJBTerminal(msg.sender))
                 && DIRECTORY.controllerOf(context.projectId) != IERC165(msg.sender)
-        ) revert JBTokenDistributor_Unauthorized();
+        ) revert JBTokenDistributor_Unauthorized({projectId: context.projectId, caller: msg.sender});
 
         // The target hook is the split's beneficiary (the IVotes token address).
         address hook = address(context.split.beneficiary);
 
         // If it's not a native-token transfer, credit the ERC-20 amount.
         if (msg.value == 0 && context.amount != 0) {
-            uint256 allowance = IERC20(context.token).allowance(msg.sender, address(this));
-            if (allowance >= context.amount) {
-                // 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);
-                uint256 delta = IERC20(context.token).balanceOf(address(this)) - balanceBefore;
-                _balanceOf[hook][IERC20(context.token)] += delta;
-                _accountedBalanceOf[IERC20(context.token)] += delta;
-            } else {
-                // Controller-prepaid path: verify actual unaccounted balance covers the declared amount.
-                uint256 actual = IERC20(context.token).balanceOf(address(this));
-                uint256 unaccounted = actual - _accountedBalanceOf[IERC20(context.token)];
-                if (unaccounted < context.amount) revert JBDistributor_UnfundedSplitCredit();
-                _accountedBalanceOf[IERC20(context.token)] += context.amount;
-                _balanceOf[hook][IERC20(context.token)] += context.amount;
-            }
+            // Pull tokens via transferFrom. Both terminals and controllers grant an ERC-20
+            // allowance before calling. Balance delta handles fee-on-transfer tokens correctly.
+            uint256 balanceBefore = IERC20(context.token).balanceOf(address(this));
+            IERC20(context.token).safeTransferFrom({from: msg.sender, to: address(this), value: context.amount});
+            uint256 delta = IERC20(context.token).balanceOf(address(this)) - balanceBefore;
+            _balanceOf[hook][IERC20(context.token)] += delta;
+            _accountedBalanceOf[IERC20(context.token)] += delta;
         } else if (msg.value != 0) {
             // Validate that context.token matches NATIVE_TOKEN to prevent cross-booking attacks.
-            if (context.token != JBConstants.NATIVE_TOKEN) revert JBTokenDistributor_TokenMismatch();
+            if (context.token != JBConstants.NATIVE_TOKEN) {
+                revert JBTokenDistributor_TokenMismatch({
+                    token: context.token, expectedToken: JBConstants.NATIVE_TOKEN, msgValue: msg.value
+                });
+            }
             // Native ETH: credit actual value received.
             _balanceOf[hook][IERC20(context.token)] += msg.value;
             _accountedBalanceOf[IERC20(context.token)] += msg.value;
@@ -138,7 +132,7 @@ contract JBTokenDistributor is JBDistributor, IJBTokenDistributor {
     /// @return canClaim True if the account matches the encoded address.
     function _canClaim(address hook, uint256 tokenId, address account) internal pure override returns (bool canClaim) {
         hook; // Silence unused variable warning.
-        if (tokenId >> 160 != 0) revert JBTokenDistributor_InvalidTokenId();
+        if (tokenId >> 160 != 0) revert JBTokenDistributor_InvalidTokenId({tokenId: tokenId});
         // The high bits were checked above, so this cast recovers the encoded address.
         // forge-lint: disable-next-line(unsafe-typecast)
         canClaim = address(uint160(tokenId)) == account;
@@ -163,7 +157,7 @@ contract JBTokenDistributor is JBDistributor, IJBTokenDistributor {
     /// @param tokenId The encoded staker address (`uint256(uint160(stakerAddress))`).
     /// @return tokenStakeAmount The delegated voting power at the round's snapshot block.
     function _tokenStake(address hook, uint256 tokenId) internal view override returns (uint256 tokenStakeAmount) {
-        if (tokenId >> 160 != 0) revert JBTokenDistributor_InvalidTokenId();
+        if (tokenId >> 160 != 0) revert JBTokenDistributor_InvalidTokenId({tokenId: tokenId});
         // The high bits were checked above, so this cast recovers the encoded address.
         // forge-lint: disable-next-line(unsafe-typecast)
         tokenStakeAmount = IVotes(hook).getPastVotes(address(uint160(tokenId)), roundSnapshotBlock[currentRound()]);