@bananapus/721-hook-v6 0.0.72 → 0.0.73

package/README.md

@@ -38,7 +38,7 @@ This repo does more than "mint NFTs on pay." It changes how payment value, tier
 | `JB721TiersHookDeployer` | Clone factory for deploying a hook for an existing project. |
 | `JB721TiersHookProjectDeployer` | Convenience deployer for launching a project with a hook already wired in. |
 | `JB721Hook` | Abstract base for 721 pay and cash-out hook behavior. |
-| `JB721Checkpoints` | Per-hook IVotes checkpoint module. Tracks historical owner checkpoints, per-tier owner-tracked voting units (`getPastTierVotingUnits`), global active vote totals (`getPastTotalActiveVotes`), and per-tier active vote totals (`getPastTierActiveVotes`). |
+| `JB721Checkpoints` | Per-hook IVotes checkpoint module. Tracks historical owner checkpoints, per-tier owner-tracked voting units (`getPastTierVotingUnits`), global active vote totals (`getPastTotalActiveVotes`), per-tier active vote totals (`getPastTotalTierActiveVotes`), and per-account active tier voting units (`getPastAccountTierActiveVotes`). |
 
 ## Mental model
 
@@ -65,7 +65,8 @@ If a bug affects supply, reserve minting, or tier lookup, it usually lives in th
 - adding a 721 hook through a deployer is easy; carrying the right ruleset behavior forward is where mistakes happen
 - projects should be explicit about whether the hook affects pay, cash out, or only metadata-facing paths
 - per-tier owner-tracked voting units are queryable via `getPastTierVotingUnits(tierId, blockNumber)`: mints, transfers, and burns write ownership history, so the trace follows owned units regardless of delegation
-- active delegated vote totals are queryable globally via `getPastTotalActiveVotes(blockNumber)` / `getTotalActiveVotes()` and per tier via `getPastTierActiveVotes(tierId, blockNumber)` / `getTierActiveVotes(tierId)`. These totals include only voting units held by accounts with a nonzero delegate, so a token in undelegated custody does not count and returned tokens become active again if the holder's delegation is still set.
+- active delegated vote totals are queryable globally via `getPastTotalActiveVotes(blockNumber)` / `getTotalActiveVotes()` and per tier via `getPastTotalTierActiveVotes(tierId, blockNumber)` / `getTotalTierActiveVotes(tierId)`. These totals include only voting units held by accounts with a nonzero delegate, so a token in undelegated custody does not count and returned tokens become active again if the holder's delegation is still set.
+- per-account active tier voting units are queryable via `getPastAccountTierActiveVotes(account, tierId, blockNumber)`. This follows the account holding the tier units, not the delegate receiving voting power, so reward distributors can cap tier-scoped claims against the holder's active units even when votes are delegated to another address.
 
 ## Where state lives
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/721-hook-v6",
-  "version": "0.0.72",
+  "version": "0.0.73",
   "license": "MIT",
   "repository": {
     "type": "git",

package/references/operations.md

@@ -12,8 +12,8 @@
 - If you edit tier config or metadata behavior, inspect the corresponding structs and interfaces in `src/structs/` and `src/interfaces/`.
 - If you edit reserve behavior, verify pending reserve counts, default reserve beneficiary semantics, and cash-out denominator effects together.
 - If you edit discount behavior, verify mint price and cash-out weight separately. They are intentionally not the same quantity.
-- If you touch checkpoint, `onTransfer`, or `delegate` behavior, verify the per-tier eligible-voting-units trace (`_tierEligibleUnitsOf`, read via `getPastTierVotingUnits`) still moves only on eligibility changes: increment on enrollment or a token's first transfer, decrement on burn, and nothing on mint (so the mint path keeps its zero added checkpoint gas). Keep it in lockstep with `ownerOfAt` eligibility.
-- Also verify the active delegated vote trace (`_activeSupplyCheckpoints`, read via `getPastTotalActiveVotes` and `getTotalActiveVotes`) moves only when voting units enter or leave nonzero delegation. It is separate from owner-based tier reward eligibility.
+- If you touch checkpoint, `onTransfer`, or `delegate` behavior, verify the per-tier eligible-voting-units trace (`_tierEligibleUnitsOf`, read via `getPastTierVotingUnits`) still moves only on eligibility changes: increment on mint or first checkpoint backfill, decrement on burn, and stay unchanged on ordinary transfers. Keep it in lockstep with `ownerOfAt` eligibility.
+- Also verify the active delegated vote traces (`_activeSupplyCheckpoints`, `_tierActiveSupplyCheckpointsOf`, and `_accountTierActiveVotesOf`) move only when voting units enter or leave nonzero delegation. They are separate from owner-based tier reward eligibility.
 - If you touch permissions, verify the caller path and permission constants still line up with the downstream ecosystem package that defines them.
 - If you touch URI behavior, confirm whether the issue belongs in this repo or in a downstream resolver contract that the hook calls.
 

package/src/JB721Checkpoints.sol

@@ -55,6 +55,13 @@ contract JB721Checkpoints is Votes, IJB721Checkpoints {
     // -------------------- internal stored properties ------------------- //
     //*********************************************************************//
 
+    /// @notice Checkpointed active voting units per account and tier.
+    /// @dev Maintained only for units held by accounts with nonzero delegates. Undelegated custody is not checkpointed
+    /// in this trace because those units are inactive for active-vote reward accounting.
+    /// @custom:param account The account to get historical active tier voting units for.
+    /// @custom:param tierId The tier to get historical active voting units for.
+    mapping(address account => mapping(uint256 tierId => Checkpoints.Trace160)) internal _accountTierActiveVotesOf;
+
     /// @notice Checkpointed token owners for historical reward eligibility.
     /// @dev Mint and transfer hooks write this automatically; `delegate` only backfills missing pre-upgrade history.
     /// @custom:param tokenId The token ID to get historical owner checkpoints for.
@@ -189,10 +196,20 @@ contract JB721Checkpoints is Votes, IJB721Checkpoints {
         // Move checkpointed voting power from the previous owner to the new owner.
         _transferVotingUnits({from: from, to: to, amount: votingUnits});
 
+        // If the sender was delegated, remove this token's tier units from the sender's active tier balance.
+        if (decreaseTierActiveVotes) {
+            _adjustAccountTierActiveVotes({account: from, tierId: tierId, amount: votingUnits, increase: false});
+        }
+
+        // If the receiver is delegated, add this token's tier units to the receiver's active tier balance.
+        if (increaseTierActiveVotes) {
+            _adjustAccountTierActiveVotes({account: to, tierId: tierId, amount: votingUnits, increase: true});
+        }
+
         // If both sides are delegated or both sides are undelegated, this tier's active total is unchanged.
         if (decreaseTierActiveVotes != increaseTierActiveVotes) {
             // Otherwise apply the one-sided active-tier delta implied by the receiver's delegated status.
-            _adjustTierActiveVotes({tierId: tierId, amount: votingUnits, increase: increaseTierActiveVotes});
+            _adjustTotalTierActiveVotes({tierId: tierId, amount: votingUnits, increase: increaseTierActiveVotes});
         }
     }
 
@@ -200,12 +217,14 @@ contract JB721Checkpoints is Votes, IJB721Checkpoints {
     // ----------------------- external views ---------------------------- //
     //*********************************************************************//
 
-    /// @notice The total delegated voting units of a tier at a past block.
-    /// @dev Counts only tier voting units held by accounts with a nonzero delegate.
+    /// @notice The delegated voting units held by an account in a tier at a past block.
+    /// @dev Counts only tier voting units held by `account` while `account` had a nonzero delegate.
+    /// @param account The account to get the delegated tier voting units of.
     /// @param tierId The tier to get the delegated voting units of.
     /// @param blockNumber The past block number to look up.
-    /// @return activeVotes The tier's delegated voting units at `blockNumber`.
-    function getPastTierActiveVotes(
+    /// @return activeVotes The account's delegated tier voting units at `blockNumber`.
+    function getPastAccountTierActiveVotes(
+        address account,
         uint256 tierId,
         uint256 blockNumber
     )
@@ -215,7 +234,8 @@ contract JB721Checkpoints is Votes, IJB721Checkpoints {
         returns (uint256 activeVotes)
     {
         // forge-lint: disable-next-line(unsafe-typecast)
-        activeVotes = _tierActiveSupplyCheckpointsOf[tierId].upperLookupRecent(uint96(_validateTimepoint(blockNumber)));
+        activeVotes =
+            _accountTierActiveVotesOf[account][tierId].upperLookupRecent(uint96(_validateTimepoint(blockNumber)));
     }
 
     /// @notice The total owner-checkpointed voting units of a tier at a past block.
@@ -243,11 +263,22 @@ contract JB721Checkpoints is Votes, IJB721Checkpoints {
         activeVotes = _activeSupplyCheckpoints.upperLookupRecent(_validateTimepoint(blockNumber));
     }
 
-    /// @notice The current total delegated voting units of a tier.
-    /// @param tierId The tier to get the current delegated voting units of.
-    /// @return activeVotes The tier's current delegated voting units.
-    function getTierActiveVotes(uint256 tierId) external view override returns (uint256 activeVotes) {
-        activeVotes = _tierActiveSupplyCheckpointsOf[tierId].latest();
+    /// @notice The total delegated voting units of a tier at a past block.
+    /// @dev Counts only tier voting units held by accounts with a nonzero delegate.
+    /// @param tierId The tier to get the delegated voting units of.
+    /// @param blockNumber The past block number to look up.
+    /// @return activeVotes The tier's delegated voting units at `blockNumber`.
+    function getPastTotalTierActiveVotes(
+        uint256 tierId,
+        uint256 blockNumber
+    )
+        external
+        view
+        override
+        returns (uint256 activeVotes)
+    {
+        // forge-lint: disable-next-line(unsafe-typecast)
+        activeVotes = _tierActiveSupplyCheckpointsOf[tierId].upperLookupRecent(uint96(_validateTimepoint(blockNumber)));
     }
 
     /// @notice The current total delegated voting units.
@@ -257,6 +288,13 @@ contract JB721Checkpoints is Votes, IJB721Checkpoints {
         activeVotes = _activeSupplyCheckpoints.latest();
     }
 
+    /// @notice The current total delegated voting units of a tier.
+    /// @param tierId The tier to get the current delegated voting units of.
+    /// @return activeVotes The tier's current delegated voting units.
+    function getTotalTierActiveVotes(uint256 tierId) external view override returns (uint256 activeVotes) {
+        activeVotes = _tierActiveSupplyCheckpointsOf[tierId].latest();
+    }
+
     /// @notice The owner of an NFT at a past block.
     /// @dev Returns `address(0)` if no ownership checkpoint exists or the query predates the first checkpoint.
     /// @param tokenId The token ID of the NFT to get the historical owner of.
@@ -354,11 +392,31 @@ contract JB721Checkpoints is Votes, IJB721Checkpoints {
     // ------------------------ private helpers -------------------------- //
     //*********************************************************************//
 
+    /// @notice Add or remove units from an account's active-voting-units checkpoint for a tier at the current block.
+    /// @param account The account whose active-voting-units trace should be updated.
+    /// @param tierId The tier whose active-voting-units trace should be updated.
+    /// @param amount The voting units to add or remove.
+    /// @param increase Whether to add `amount`; if false, `amount` is removed.
+    function _adjustAccountTierActiveVotes(address account, uint256 tierId, uint256 amount, bool increase) private {
+        // Ignore zero-unit updates because they do not change the account's active tier total.
+        if (amount == 0) return;
+
+        // Keep a reference to the account's active-voting-units trace for this tier.
+        Checkpoints.Trace160 storage trace = _accountTierActiveVotesOf[account][tierId];
+
+        // Calculate the next account-tier active total from its latest checkpointed value.
+        uint256 updated = increase ? trace.latest() + amount : trace.latest() - amount;
+
+        // Write the new account-tier active total at the current block.
+        // forge-lint: disable-next-line(unsafe-typecast)
+        trace.push({key: uint96(block.number), value: uint160(updated)});
+    }
+
     /// @notice Add or remove units from a tier's active-voting-units checkpoint at the current block.
     /// @param tierId The tier whose active-voting-units trace to update.
     /// @param amount The voting units to add or remove.
     /// @param increase Whether to add `amount`; if false, `amount` is removed.
-    function _adjustTierActiveVotes(uint256 tierId, uint256 amount, bool increase) private {
+    function _adjustTotalTierActiveVotes(uint256 tierId, uint256 amount, bool increase) private {
         // Ignore zero-unit updates because they do not change this tier's active total.
         if (amount == 0) return;
 
@@ -389,7 +447,10 @@ contract JB721Checkpoints is Votes, IJB721Checkpoints {
 
             // Only write checkpoints for tiers whose active totals actually change.
             if (tierVotingUnits != 0) {
-                _adjustTierActiveVotes({tierId: tierId, amount: tierVotingUnits, increase: increase});
+                _adjustTotalTierActiveVotes({tierId: tierId, amount: tierVotingUnits, increase: increase});
+                _adjustAccountTierActiveVotes({
+                    account: account, tierId: tierId, amount: tierVotingUnits, increase: increase
+                });
             }
 
             unchecked {

package/src/interfaces/IJB721Checkpoints.sol

@@ -15,12 +15,20 @@ interface IJB721Checkpoints is IERC5805, IJBActiveVotes {
     // forge-lint: disable-next-line(mixed-case-function)
     function STORE() external view returns (IJB721TiersHookStore store);
 
-    /// @notice The total delegated voting units of a tier at a past block.
-    /// @dev Counts only tier voting units held by accounts with a nonzero delegate.
+    /// @notice The delegated voting units held by an account in a tier at a past block.
+    /// @dev Counts only tier voting units held by `account` while `account` had a nonzero delegate.
+    /// @param account The account to get the delegated tier voting units of.
     /// @param tierId The tier to get the delegated voting units of.
     /// @param blockNumber The past block number to look up.
-    /// @return activeVotes The tier's delegated voting units at `blockNumber`.
-    function getPastTierActiveVotes(uint256 tierId, uint256 blockNumber) external view returns (uint256 activeVotes);
+    /// @return activeVotes The account's delegated tier voting units at `blockNumber`.
+    function getPastAccountTierActiveVotes(
+        address account,
+        uint256 tierId,
+        uint256 blockNumber
+    )
+        external
+        view
+        returns (uint256 activeVotes);
 
     /// @notice The total owner-checkpointed voting units of a tier at a past block.
     /// @dev Owner-checkpointed voting units are the tier's total owned units, regardless of delegation status.
@@ -29,10 +37,23 @@ interface IJB721Checkpoints is IERC5805, IJBActiveVotes {
     /// @return votingUnits The tier's owner-checkpointed voting units at `blockNumber`.
     function getPastTierVotingUnits(uint256 tierId, uint256 blockNumber) external view returns (uint256 votingUnits);
 
+    /// @notice The total delegated voting units of a tier at a past block.
+    /// @dev Counts only tier voting units held by accounts with a nonzero delegate.
+    /// @param tierId The tier to get the delegated voting units of.
+    /// @param blockNumber The past block number to look up.
+    /// @return activeVotes The tier's delegated voting units at `blockNumber`.
+    function getPastTotalTierActiveVotes(
+        uint256 tierId,
+        uint256 blockNumber
+    )
+        external
+        view
+        returns (uint256 activeVotes);
+
     /// @notice The current total delegated voting units of a tier.
     /// @param tierId The tier to get the current delegated voting units of.
     /// @return activeVotes The tier's current delegated voting units.
-    function getTierActiveVotes(uint256 tierId) external view returns (uint256 activeVotes);
+    function getTotalTierActiveVotes(uint256 tierId) external view returns (uint256 activeVotes);
 
     /// @notice The hook that this module tracks voting power for.
     /// @return hookAddress The hook address.