@bananapus/721-hook-v6 0.0.69 → 0.0.70

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 plus per-tier eligible voting units (`getPastTierVotingUnits`) for tier-scoped reward distribution. |
+| `JB721Checkpoints` | Per-hook IVotes checkpoint module. Tracks historical owner checkpoints, per-tier eligible voting units (`getPastTierVotingUnits`) for tier-scoped reward distribution, and active delegated vote totals (`getPastTotalActiveVotes`). |
 
 ## Mental model
 
@@ -65,6 +65,7 @@ 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 eligible voting units are queryable via `getPastTierVotingUnits(tierId, blockNumber)` for tier-scoped reward denominators, but minting alone does not enroll a token: a token only counts toward that total once it is enrolled (`delegate(address, uint256[])`) or transferred for the first time, and stops counting when burned
+- active delegated vote totals are queryable via `getPastTotalActiveVotes(blockNumber)` and `getTotalActiveVotes()`. These totals include only voting units held by accounts with a nonzero delegate, so a token in undelegated custody does not count; this is a governance/reward-participation primitive, not the owner-based tier reward denominator.
 
 ## Where state lives
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/721-hook-v6",
-  "version": "0.0.69",
+  "version": "0.0.70",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -26,7 +26,7 @@
   },
   "dependencies": {
     "@bananapus/address-registry-v6": "^0.0.33",
-    "@bananapus/core-v6": "^0.0.81",
+    "@bananapus/core-v6": "^0.0.85",
     "@bananapus/ownable-v6": "^0.0.36",
     "@bananapus/permission-ids-v6": "^0.0.29",
     "@openzeppelin/contracts": "5.6.1",

package/references/operations.md

@@ -13,6 +13,7 @@
 - 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 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/references/runtime.md

@@ -20,7 +20,7 @@
 - Reserve accounting: edits around `reserveFrequency`, pending reserves, or owner minting must preserve the store's supply protections.
 - Tier splits: split forwarding changes affect both payer economics and project treasury accounting. Check both `beforePayRecordedWith` and the distribution path.
 - Discount behavior: price discounts affect mint eligibility but cash-out weight still tracks the original tier price. Do not conflate the two.
-- Voting units: verify whether a tier uses explicit voting units or falls back to price-based voting power before changing governance-facing math.
+- Voting units: verify whether a tier uses explicit voting units or falls back to price-based voting power before changing governance-facing math. Active vote totals count only units delegated to nonzero delegates and are separate from tier reward eligibility.
 - Tier removal and cleanup: removing tiers is not the same as cleaning the sorted tier list. Storage cleanup behavior matters.
 - Default reserve beneficiary changes: they affect which tiers count pending reserves unless a tier-specific beneficiary overrides it. That is an economic change, not just an admin update.
 

package/src/JB721Checkpoints.sol

@@ -1,9 +1,10 @@
 // SPDX-License-Identifier: MIT
 pragma solidity 0.8.28;
 
-import {IERC721} from "@openzeppelin/contracts/token/ERC721/IERC721.sol";
 import {Votes} from "@openzeppelin/contracts/governance/utils/Votes.sol";
+import {IERC721} from "@openzeppelin/contracts/token/ERC721/IERC721.sol";
 import {EIP712} from "@openzeppelin/contracts/utils/cryptography/EIP712.sol";
+import {SafeCast} from "@openzeppelin/contracts/utils/math/SafeCast.sol";
 import {Checkpoints} from "@openzeppelin/contracts/utils/structs/Checkpoints.sol";
 
 import {IJB721Checkpoints} from "./interfaces/IJB721Checkpoints.sol";
@@ -19,6 +20,7 @@ import {IJB721TiersHookStore} from "./interfaces/IJB721TiersHookStore.sol";
 /// `address(this)` — correct behavior, tiny gas overhead.
 contract JB721Checkpoints is Votes, IJB721Checkpoints {
     using Checkpoints for Checkpoints.Trace160;
+    using Checkpoints for Checkpoints.Trace208;
 
     //*********************************************************************//
     // --------------------------- custom errors ------------------------- //
@@ -61,6 +63,13 @@ contract JB721Checkpoints is Votes, IJB721Checkpoints {
     /// @custom:param tierId The tier to get the historical eligible voting units for.
     mapping(uint256 tierId => Checkpoints.Trace160) internal _tierEligibleUnitsOf;
 
+    //*********************************************************************//
+    // -------------------- private stored properties -------------------- //
+    //*********************************************************************//
+
+    /// @notice The total voting units currently delegated to nonzero delegates.
+    Checkpoints.Trace208 private _activeSupplyCheckpoints;
+
     //*********************************************************************//
     // -------------------------- constructor ---------------------------- //
     //*********************************************************************//
@@ -172,6 +181,21 @@ contract JB721Checkpoints is Votes, IJB721Checkpoints {
         return _tierEligibleUnitsOf[tierId].upperLookupRecent(uint96(_validateTimepoint(blockNumber)));
     }
 
+    /// @notice The total delegated voting units at a past block.
+    /// @dev This tracks delegated vote participation and is separate from tier reward eligibility.
+    /// @param timepoint The past block number to look up.
+    /// @return activeVotes The total voting units delegated to nonzero delegates at `timepoint`.
+    function getPastTotalActiveVotes(uint256 timepoint) external view override returns (uint256 activeVotes) {
+        activeVotes = _activeSupplyCheckpoints.upperLookupRecent(_validateTimepoint(timepoint));
+    }
+
+    /// @notice The current total delegated voting units.
+    /// @dev This tracks delegated vote participation and is separate from tier reward eligibility.
+    /// @return activeVotes The current total voting units delegated to nonzero delegates.
+    function getTotalActiveVotes() external view override returns (uint256 activeVotes) {
+        activeVotes = _activeSupplyCheckpoints.latest();
+    }
+
     /// @notice The owner of an NFT at a past block.
     /// @dev Returns `address(0)` for tokens that have never been enrolled (via `delegate(address, uint256[])`) or
     /// transferred. Unenrolled tokens are ineligible for snapshot-based distribution.
@@ -194,6 +218,60 @@ contract JB721Checkpoints is Votes, IJB721Checkpoints {
         return address(uint160(checkpoints.upperLookupRecent(blockNumber96)));
     }
 
+    //*********************************************************************//
+    // ---------------------- internal transactions ---------------------- //
+    //*********************************************************************//
+
+    /// @notice Track active-vote-total changes when an account changes its delegate.
+    /// @dev Delegating to a nonzero address makes all of `account`'s voting units active. Clearing delegation removes
+    /// all of `account`'s voting units from the active total. Redelegating between two nonzero delegates only moves
+    /// votes inside OZ `Votes`, so the active total does not change.
+    /// @param account The account whose delegation is changing.
+    /// @param delegatee The new delegate. Use `address(0)` to clear delegation.
+    function _delegate(address account, address delegatee) internal virtual override {
+        // Read the current delegate before OZ mutates the delegate mapping.
+        address oldDelegate = delegates(account);
+
+        // Read the account's current voting units so any active-total delta matches the units OZ moves.
+        uint256 votingUnits = _getVotingUnits(account);
+
+        // Let OZ update the delegate mapping and the per-delegate vote checkpoints.
+        super._delegate({account: account, delegatee: delegatee});
+
+        // If the account had no delegate and now has one, its voting units just became active.
+        if (oldDelegate == address(0) && delegatee != address(0)) {
+            // Add the account's voting units to the checkpointed active total.
+            _updateActiveVotes({amount: votingUnits, increase: true});
+        } else if (oldDelegate != address(0) && delegatee == address(0)) {
+            // If the account had a delegate and now has none, its voting units just became inactive.
+            _updateActiveVotes({amount: votingUnits, increase: false});
+        }
+    }
+
+    /// @notice Track active-vote-total changes when voting units move between accounts.
+    /// @dev Moving voting units between two accounts with the same delegation status does not change the active total.
+    /// Moving voting units out of a delegated account and into an undelegated account decreases the active total, while
+    /// moving voting units out of an undelegated account and into a delegated account increases it.
+    /// @param from The account whose voting units are leaving. `address(0)` means the units are being minted.
+    /// @param to The account whose voting units are arriving. `address(0)` means the units are being burned.
+    /// @param amount The voting units moving between `from` and `to`.
+    function _transferVotingUnits(address from, address to, uint256 amount) internal virtual override {
+        // The active total decreases if units leave an account that already has a nonzero delegate.
+        bool decreaseActiveVotes = from != address(0) && delegates(from) != address(0);
+
+        // The active total increases if units arrive at an account that already has a nonzero delegate.
+        bool increaseActiveVotes = to != address(0) && delegates(to) != address(0);
+
+        // Let OZ update total voting-unit supply and per-delegate checkpoints first.
+        super._transferVotingUnits({from: from, to: to, amount: amount});
+
+        // If both sides are delegated or both sides are undelegated, the active total is unchanged.
+        if (decreaseActiveVotes == increaseActiveVotes) return;
+
+        // Otherwise apply the one-sided active-total delta implied by the receiver's delegated status.
+        _updateActiveVotes({amount: amount, increase: increaseActiveVotes});
+    }
+
     //*********************************************************************//
     // ----------------------- internal views ---------------------------- //
     //*********************************************************************//
@@ -210,6 +288,23 @@ contract JB721Checkpoints is Votes, IJB721Checkpoints {
     // ------------------------ private helpers -------------------------- //
     //*********************************************************************//
 
+    /// @notice Update the checkpointed total of delegated voting units.
+    /// @dev Writes at most one active-total checkpoint at the current OZ clock. A zero amount is ignored so zero-value
+    /// delegation or transfer hooks do not create empty checkpoints.
+    /// @param amount The amount of voting units to add or remove.
+    /// @param increase Whether to add `amount`; if false, `amount` is removed.
+    function _updateActiveVotes(uint256 amount, bool increase) private {
+        // Ignore zero-unit updates because they do not change the active total.
+        if (amount == 0) return;
+
+        // Calculate the next active total by adding or subtracting from the latest checkpointed value.
+        uint256 updated =
+            increase ? _activeSupplyCheckpoints.latest() + amount : _activeSupplyCheckpoints.latest() - amount;
+
+        // Write the new active total at the current ERC-6372 clock using the same uint208 width as OZ `Votes`.
+        _activeSupplyCheckpoints.push({key: clock(), value: SafeCast.toUint208(updated)});
+    }
+
     /// @notice Add or remove units from a tier's eligible-voting-units checkpoint at the current block.
     /// @param tierId The tier whose eligible-voting-units trace to update.
     /// @param amount The voting units to add or remove.

package/src/interfaces/IJB721Checkpoints.sol

@@ -1,13 +1,19 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.0;
 
+import {IJBActiveVotes} from "@bananapus/core-v6/src/interfaces/IJBActiveVotes.sol";
 import {IERC5805} from "@openzeppelin/contracts/interfaces/IERC5805.sol";
 import {IJB721TiersHookStore} from "./IJB721TiersHookStore.sol";
 
 /// @notice A checkpoint module that provides IVotes-compatible checkpointed voting power for a JB721TiersHook.
 /// @dev Deployed as a clone via JB721CheckpointsDeployer during hook initialization. One module per hook.
 /// Pass this address to JBTokenDistributor as the IVotes token.
-interface IJB721Checkpoints is IERC5805 {
+interface IJB721Checkpoints is IERC5805, IJBActiveVotes {
+    /// @notice The store that holds tier and voting data for the hook's NFTs.
+    /// @return The store contract.
+    // forge-lint: disable-next-line(mixed-case-function)
+    function STORE() external view returns (IJB721TiersHookStore);
+
     /// @notice The total eligible voting units of a tier at a past block.
     /// @dev "Eligible" means a token has an owner checkpoint: it was enrolled via `delegate(address,uint256[])` or
     /// transferred at least once. Minted-but-unenrolled tokens are excluded, mirroring `ownerOfAt` eligibility, and
@@ -30,11 +36,6 @@ interface IJB721Checkpoints is IERC5805 {
     /// @return The owner of the token at `blockNumber`, or zero if the token is unenrolled or has no known owner.
     function ownerOfAt(uint256 tokenId, uint256 blockNumber) external view returns (address);
 
-    /// @notice The store that holds tier and voting data for the hook's NFTs.
-    /// @return The store contract.
-    // forge-lint: disable-next-line(mixed-case-function)
-    function STORE() external view returns (IJB721TiersHookStore);
-
     /// @notice Delegates voting power and enrolls tokens for distribution eligibility.
     /// @dev Writes per-token owner checkpoints so `ownerOfAt` can prove ownership at past blocks.
     /// Only the current token owner can enroll. Tokens without checkpoints are ineligible for snapshot-based