@bananapus/distributor-v6 0.0.20 → 0.0.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/distributor-v6",
-  "version": "0.0.20",
+  "version": "0.0.22",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -26,9 +26,9 @@
     "deploy:testnets": "source ./.env && npx sphinx propose ./script/Deploy.s.sol --networks testnets"
   },
   "dependencies": {
-    "@bananapus/721-hook-v6": "^0.0.52",
-    "@bananapus/core-v6": "^0.0.55",
-    "@bananapus/permission-ids-v6": "^0.0.25",
+    "@bananapus/721-hook-v6": "^0.0.54",
+    "@bananapus/core-v6": "^0.0.57",
+    "@bananapus/permission-ids-v6": "^0.0.26",
     "@openzeppelin/contracts": "5.6.1",
     "@prb/math": "4.1.1"
   },

package/src/JB721Distributor.sol

@@ -9,7 +9,6 @@ import {IJBTerminal} from "@bananapus/core-v6/src/interfaces/IJBTerminal.sol";
 import {JBConstants} from "@bananapus/core-v6/src/libraries/JBConstants.sol";
 import {JBSplitHookContext} from "@bananapus/core-v6/src/structs/JBSplitHookContext.sol";
 import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
-import {SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
 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";
@@ -27,12 +26,13 @@ import {JBVestingData} from "./structs/JBVestingData.sol";
 /// calculation and their unvested rewards can be reclaimed via `releaseForfeitedRewards`.
 /// @dev Implements `IJBSplitHook` so it can receive tokens directly from Juicebox project payout splits.
 contract JB721Distributor is JBDistributor, IJB721Distributor {
-    using SafeERC20 for IERC20;
-
     //*********************************************************************//
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
+    /// @notice Thrown when native ETH does not match the split hook context amount.
+    error JB721Distributor_NativeAmountMismatch(uint256 msgValue, uint256 contextAmount);
+
     /// @notice Thrown when native ETH is sent but context.token is not NATIVE_TOKEN.
     error JB721Distributor_TokenMismatch(address token, address expectedToken, uint256 msgValue);
 
@@ -116,25 +116,32 @@ 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, credit the ERC-20 amount.
-        if (msg.value == 0 && context.amount != 0) {
-            // 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) {
+        // Native splits must conserve the terminal's stated context amount exactly.
+        if (context.token == JBConstants.NATIVE_TOKEN) {
+            if (msg.value != context.amount) {
+                revert JB721Distributor_NativeAmountMismatch({msgValue: msg.value, contextAmount: context.amount});
+            }
+
+            if (msg.value != 0) {
+                _balanceOf[hook][IERC20(context.token)] += msg.value;
+                _accountedBalanceOf[IERC20(context.token)] += msg.value;
+            }
+        } else {
+            // Validate that native ETH is not cross-booked under an ERC-20 token.
+            if (msg.value != 0) {
                 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;
+
+            if (context.amount == 0) return;
+
+            // Pull tokens via transferFrom. Both terminals and controllers grant an ERC-20
+            // allowance before calling. Balance delta handles fee-on-transfer tokens correctly.
+            uint256 delta =
+                _acceptErc20FundsFrom({token: IERC20(context.token), from: msg.sender, amount: context.amount});
+            _balanceOf[hook][IERC20(context.token)] += delta;
+            _accountedBalanceOf[IERC20(context.token)] += delta;
         }
     }
 
@@ -424,30 +431,31 @@ contract JB721Distributor is JBDistributor, IJB721Distributor {
             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.
         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});
 
+        // If the pro-rata amount rounds to zero, do not consume the owner's voting budget.
+        if (tokenAmount == 0) return (0, newUniqueCount);
+
+        // Record that this owner has consumed additional voting power from their budget.
+        consumed[ownerIndex] += stake;
+
         // 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({
-                hook: ctx.hook,
-                tokenId: tokenId,
-                token: ctx.token,
-                amount: tokenAmount,
-                vestingReleaseRound: ctx.vestingReleaseRound
-            });
-        }
+        // 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({
+            hook: ctx.hook,
+            tokenId: tokenId,
+            token: ctx.token,
+            amount: tokenAmount,
+            vestingReleaseRound: ctx.vestingReleaseRound
+        });
     }
 }

package/src/JBDistributor.sol

@@ -7,6 +7,7 @@ import {SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol
 import {mulDiv} from "@prb/math/src/Common.sol";
 
 import {IJBDistributor} from "./interfaces/IJBDistributor.sol";
+import {JBVestingMath} from "./libraries/JBVestingMath.sol";
 import {JBTokenSnapshotData} from "./structs/JBTokenSnapshotData.sol";
 import {JBVestingData} from "./structs/JBVestingData.sol";
 
@@ -27,18 +28,21 @@ abstract contract JBDistributor is IJBDistributor {
     /// @notice Thrown when an empty tokenIds array is passed.
     error JBDistributor_EmptyTokenIds(uint256 tokenIdCount);
 
+    /// @notice Thrown when the round duration is zero.
+    error JBDistributor_InvalidRoundDuration(uint256 roundDuration);
+
     /// @notice Thrown when a native ETH transfer fails.
     error JBDistributor_NativeTransferFailed(address beneficiary, uint256 amount);
 
     /// @notice Thrown when the caller does not have access to the token.
     error JBDistributor_NoAccess(address hook, uint256 tokenId, address account);
 
-    /// @notice Thrown when the round duration is zero.
-    error JBDistributor_InvalidRoundDuration(uint256 roundDuration);
-
     /// @notice Thrown when there is nothing to distribute for a token in the current round.
     error JBDistributor_NothingToDistribute(address hook, address token, uint256 round);
 
+    /// @notice Thrown when an ERC-20 reenters a funding balance-delta measurement.
+    error JBDistributor_ReentrantTokenTransfer(address token);
+
     /// @notice Thrown when unexpected native ETH is sent with an ERC-20 operation.
     error JBDistributor_UnexpectedNativeValue(uint256 msgValue, address token);
 
@@ -115,6 +119,13 @@ abstract contract JBDistributor is IJBDistributor {
     /// @custom:param round The round to which the data applies.
     mapping(address hook => mapping(IERC20 token => mapping(uint256 round => bool))) internal _snapshotInitializedFor;
 
+    //*********************************************************************//
+    // ------------------- transient stored properties ------------------- //
+    //*********************************************************************//
+
+    /// @notice The ERC-20 whose incoming balance delta is currently being measured.
+    address transient _acceptingToken;
+
     //*********************************************************************//
     // -------------------------- constructor ---------------------------- //
     //*********************************************************************//
@@ -141,6 +152,11 @@ abstract contract JBDistributor is IJBDistributor {
     /// @param tokenIds The staker token IDs to claim rewards for.
     /// @param tokens The reward tokens to begin vesting.
     function beginVesting(address hook, uint256[] calldata tokenIds, IERC20[] calldata tokens) external override {
+        // Reward accounting cannot change while an ERC-20 `transferFrom` is in progress. A callback-capable reward
+        // token could otherwise snapshot, vest, or collect against balances between `balanceBefore` and
+        // `balanceAfter`, distorting the delta credited to the funder.
+        _requireNotAcceptingToken();
+
         // Revert if no token IDs are provided.
         if (tokenIds.length == 0) revert JBDistributor_EmptyTokenIds({tokenIdCount: tokenIds.length});
 
@@ -203,9 +219,7 @@ abstract contract JBDistributor is IJBDistributor {
                 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({from: msg.sender, to: address(this), value: amount});
-            amount = token.balanceOf(address(this)) - balanceBefore;
+            amount = _acceptErc20FundsFrom({token: token, from: msg.sender, amount: amount});
         }
         _balanceOf[hook][token] += amount;
         _accountedBalanceOf[token] += amount;
@@ -233,6 +247,9 @@ abstract contract JBDistributor is IJBDistributor {
         external
         override
     {
+        // Do not let reward-token callbacks mutate vesting state during inbound balance-delta accounting.
+        _requireNotAcceptingToken();
+
         // Make sure that all tokens are burned.
         for (uint256 i; i < tokenIds.length;) {
             if (!_tokenBurned({hook: hook, tokenId: tokenIds[i]})) {
@@ -285,7 +302,9 @@ abstract contract JBDistributor is IJBDistributor {
             JBVestingData memory vesting = vestingDataOf[hook][tokenId][token][vestedIndex];
 
             // Use `original - alreadyPaid` to include rounding dust in the remaining amount.
-            tokenAmount += vesting.amount - mulDiv({x: vesting.amount, y: vesting.shareClaimed, denominator: MAX_SHARE});
+            tokenAmount += JBVestingMath.unclaimedAmountOf({
+                amount: vesting.amount, shareClaimed: vesting.shareClaimed, maxShare: MAX_SHARE
+            });
 
             unchecked {
                 ++vestedIndex;
@@ -324,23 +343,22 @@ abstract contract JBDistributor is IJBDistributor {
             // Keep a reference to the vested data being iterated on.
             JBVestingData memory vesting = vestingDataOf[hook][tokenId][token][vestedIndex];
 
-            // Calculate the share amount that is locked.
-            if (vesting.releaseRound > round) {
-                lockedShare = (vesting.releaseRound - round) * MAX_SHARE / vestingRounds;
-            }
+            lockedShare = JBVestingMath.lockedShareOf({
+                releaseRound: vesting.releaseRound,
+                currentRound: round,
+                vestingRounds: vestingRounds,
+                maxShare: MAX_SHARE
+            });
 
-            if (lockedShare == 0 && vesting.shareClaimed < MAX_SHARE) {
-                // Final unlock: compute remaining as `original - alreadyPaid` to include dust.
-                tokenAmount += vesting.amount
-                - mulDiv({x: vesting.amount, y: vesting.shareClaimed, denominator: MAX_SHARE});
-            } else {
-                uint256 newShareClaimed = MAX_SHARE - lockedShare;
-                if (newShareClaimed > vesting.shareClaimed) {
-                    tokenAmount += mulDiv({
-                        x: vesting.amount, y: newShareClaimed - vesting.shareClaimed, denominator: MAX_SHARE
-                    });
-                }
-            }
+            // Calculate the newly unlocked amount from cumulative shares rather than the incremental share delta.
+            // Incremental floor rounding can otherwise underpay partial collections and leave dust stranded.
+            (uint256 claimAmount,) = JBVestingMath.newlyClaimableAmountOf({
+                amount: vesting.amount,
+                shareClaimed: vesting.shareClaimed,
+                lockedShare: lockedShare,
+                maxShare: MAX_SHARE
+            });
+            tokenAmount += claimAmount;
 
             unchecked {
                 ++vestedIndex;
@@ -400,6 +418,10 @@ abstract contract JBDistributor is IJBDistributor {
         public
         override
     {
+        // Collections transfer reward tokens out. If this runs inside the same reward token's inbound transfer, the
+        // outgoing transfer can net against the incoming balance delta and strand the new funds unaccounted.
+        _requireNotAcceptingToken();
+
         // Revert if no token IDs are provided.
         if (tokenIds.length == 0) revert JBDistributor_EmptyTokenIds({tokenIdCount: tokenIds.length});
 
@@ -459,6 +481,40 @@ abstract contract JBDistributor is IJBDistributor {
     // ---------------------- internal transactions ---------------------- //
     //*********************************************************************//
 
+    /// @notice Accepts an ERC-20 funding transfer and returns the actual balance delta.
+    /// @param token The ERC-20 token to accept.
+    /// @param from The address to pull tokens from.
+    /// @param amount The nominal amount to pull.
+    /// @return acceptedAmount The actual amount received.
+    function _acceptErc20FundsFrom(
+        IERC20 token,
+        address from,
+        uint256 amount
+    )
+        internal
+        returns (uint256 acceptedAmount)
+    {
+        // Arm the scoped guard before any token call, including `balanceOf`, because reward tokens are arbitrary and
+        // an upgradeable or adversarial token can reenter from either the snapshot or transfer path.
+        address tokenBeingAccepted = _acceptingToken;
+        if (tokenBeingAccepted != address(0)) revert JBDistributor_ReentrantTokenTransfer(tokenBeingAccepted);
+        _acceptingToken = address(token);
+
+        // Snapshot this contract's token balance after the guard is armed so fee-on-transfer tokens are credited by the
+        // actual amount received instead of the caller-provided nominal `amount`.
+        uint256 balanceBefore = token.balanceOf(address(this));
+
+        // Pull the nominal amount from the funder; SafeERC20 handles tokens that do not return a boolean.
+        token.safeTransferFrom({from: from, to: address(this), value: amount});
+
+        // Credit only the balance delta. This supports fee-on-transfer tokens and ignores any overstatement in
+        // `amount`.
+        acceptedAmount = token.balanceOf(address(this)) - balanceBefore;
+
+        // Close the transfer window after the token balance has been measured.
+        _acceptingToken = address(0);
+    }
+
     /// @notice Ensures that a snapshot block is recorded for the given round.
     /// @dev Uses `block.number - 1` because `IVotes.getPastVotes` requires a strictly past block.
     /// @param round The round to ensure a snapshot block for.
@@ -592,26 +648,26 @@ abstract contract JBDistributor is IJBDistributor {
                 // 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;
+                uint256 lockedShare = JBVestingMath.lockedShareOf({
+                    releaseRound: vesting.releaseRound,
+                    currentRound: round,
+                    vestingRounds: vestingRounds,
+                    maxShare: MAX_SHARE
+                });
 
-                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({x: vesting.amount, y: vesting.shareClaimed, denominator: MAX_SHARE});
-                } else if (MAX_SHARE - lockedShare > vesting.shareClaimed) {
-                    claimAmount = mulDiv({
-                        x: vesting.amount, y: MAX_SHARE - lockedShare - vesting.shareClaimed, denominator: MAX_SHARE
-                    });
-                }
+                // Match `claimedFor`/`collectableFor` by using the difference between cumulative rounded claims.
+                // Rounding each incremental share independently can underpay partial unlocks and leave
+                // `totalVestingAmountOf` larger than the remaining claims.
+                (uint256 claimAmount,) = JBVestingMath.newlyClaimableAmountOf({
+                    amount: vesting.amount,
+                    shareClaimed: vesting.shareClaimed,
+                    lockedShare: lockedShare,
+                    maxShare: MAX_SHARE
+                });
 
                 if (claimAmount != 0) {
+                    // Persist the cumulative unlocked share, not just this round's delta, so later collections
+                    // compare against the same rounded checkpoint that produced `claimAmount`.
                     vestings[vestedIndex].shareClaimed = MAX_SHARE - lockedShare;
                     totalTokenAmount += claimAmount;
                     emit Collected({
@@ -732,6 +788,14 @@ abstract contract JBDistributor is IJBDistributor {
     /// @return canClaim True if the account can collect rewards for this token ID.
     function _canClaim(address hook, uint256 tokenId, address account) internal view virtual returns (bool canClaim);
 
+    /// @notice Revert if called while an inbound ERC-20 transfer is being measured.
+    /// @dev Reward tokens are arbitrary contracts. This guard prevents token callbacks from mutating distributor
+    /// accounting midway through a balance-delta measurement.
+    function _requireNotAcceptingToken() internal view {
+        address token = _acceptingToken;
+        if (token != address(0)) revert JBDistributor_ReentrantTokenTransfer(token);
+    }
+
     /// @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`.
     /// @param hook The hook the token belongs to.

package/src/JBTokenDistributor.sol

@@ -8,7 +8,6 @@ import {JBConstants} from "@bananapus/core-v6/src/libraries/JBConstants.sol";
 import {JBSplitHookContext} from "@bananapus/core-v6/src/structs/JBSplitHookContext.sol";
 import {IVotes} from "@openzeppelin/contracts/governance/utils/IVotes.sol";
 import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
-import {SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
 import {IERC165} from "@openzeppelin/contracts/utils/introspection/IERC165.sol";
 
 import {IJBTokenDistributor} from "./interfaces/IJBTokenDistributor.sol";
@@ -22,8 +21,6 @@ import {JBDistributor} from "./JBDistributor.sol";
 /// Holders must delegate (even to themselves) to participate. Non-delegated supply stays in pool for future rounds.
 /// @dev Implements `IJBSplitHook` so it can receive tokens directly from Juicebox project payout splits.
 contract JBTokenDistributor is JBDistributor, IJBTokenDistributor {
-    using SafeERC20 for IERC20;
-
     //*********************************************************************//
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
@@ -31,6 +28,9 @@ 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(uint256 tokenId);
 
+    /// @notice Thrown when native ETH does not match the split hook context amount.
+    error JBTokenDistributor_NativeAmountMismatch(uint256 msgValue, uint256 contextAmount);
+
     /// @notice Thrown when native ETH is sent but context.token is not NATIVE_TOKEN.
     error JBTokenDistributor_TokenMismatch(address token, address expectedToken, uint256 msgValue);
 
@@ -86,25 +86,32 @@ contract JBTokenDistributor is JBDistributor, IJBTokenDistributor {
         // 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) {
-            // 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) {
+        // Native splits must conserve the terminal's stated context amount exactly.
+        if (context.token == JBConstants.NATIVE_TOKEN) {
+            if (msg.value != context.amount) {
+                revert JBTokenDistributor_NativeAmountMismatch({msgValue: msg.value, contextAmount: context.amount});
+            }
+
+            if (msg.value != 0) {
+                _balanceOf[hook][IERC20(context.token)] += msg.value;
+                _accountedBalanceOf[IERC20(context.token)] += msg.value;
+            }
+        } else {
+            // Validate that native ETH is not cross-booked under an ERC-20 token.
+            if (msg.value != 0) {
                 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;
+
+            if (context.amount == 0) return;
+
+            // Pull tokens via transferFrom. Both terminals and controllers grant an ERC-20
+            // allowance before calling. Balance delta handles fee-on-transfer tokens correctly.
+            uint256 delta =
+                _acceptErc20FundsFrom({token: IERC20(context.token), from: msg.sender, amount: context.amount});
+            _balanceOf[hook][IERC20(context.token)] += delta;
+            _accountedBalanceOf[IERC20(context.token)] += delta;
         }
     }
 

package/src/libraries/JBVestingMath.sol

@@ -0,0 +1,74 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.28;
+
+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
+    /// `releaseRound - currentRound <= vestingRounds` whenever `releaseRound > currentRound`.
+    /// @param releaseRound The round when the entry is fully unlocked.
+    /// @param currentRound The current distributor round.
+    /// @param vestingRounds The number of rounds in the vesting period.
+    /// @param maxShare The share value representing 100%.
+    /// @return lockedShare The share of the entry still locked.
+    function lockedShareOf(
+        uint256 releaseRound,
+        uint256 currentRound,
+        uint256 vestingRounds,
+        uint256 maxShare
+    )
+        internal
+        pure
+        returns (uint256 lockedShare)
+    {
+        if (releaseRound > currentRound) lockedShare = (releaseRound - currentRound) * maxShare / vestingRounds;
+    }
+
+    /// @notice The newly claimable amount for a vesting entry at a locked-share checkpoint.
+    /// @param amount The original vesting entry amount.
+    /// @param shareClaimed The cumulative share already claimed.
+    /// @param lockedShare The share of the entry still locked.
+    /// @param maxShare The share value representing 100%.
+    /// @return claimAmount The newly unlocked amount.
+    /// @return newShareClaimed The cumulative share that should be stored if `claimAmount` is nonzero.
+    function newlyClaimableAmountOf(
+        uint256 amount,
+        uint256 shareClaimed,
+        uint256 lockedShare,
+        uint256 maxShare
+    )
+        internal
+        pure
+        returns (uint256 claimAmount, uint256 newShareClaimed)
+    {
+        if (lockedShare == 0 && shareClaimed < maxShare) {
+            return (unclaimedAmountOf({amount: amount, shareClaimed: shareClaimed, maxShare: maxShare}), maxShare);
+        }
+
+        newShareClaimed = maxShare - lockedShare;
+        if (newShareClaimed > shareClaimed) {
+            claimAmount = mulDiv({x: amount, y: newShareClaimed, denominator: maxShare})
+                - mulDiv({x: amount, y: shareClaimed, denominator: maxShare});
+        }
+    }
+
+    /// @notice The amount remaining after the previously claimed share is deducted.
+    /// @dev Computing `amount - paid` releases any floor-division dust on the final unlock.
+    /// @param amount The original vesting entry amount.
+    /// @param shareClaimed The cumulative share already claimed.
+    /// @param maxShare The share value representing 100%.
+    /// @return unclaimedAmount The entry amount not yet claimed.
+    function unclaimedAmountOf(
+        uint256 amount,
+        uint256 shareClaimed,
+        uint256 maxShare
+    )
+        internal
+        pure
+        returns (uint256 unclaimedAmount)
+    {
+        unclaimedAmount = amount - mulDiv({x: amount, y: shareClaimed, denominator: maxShare});
+    }
+}