@bananapus/core-v6 0.0.82 → 0.0.84

package/README.md

@@ -15,7 +15,7 @@ In-repo docs (entry points for this repo):
 - [AUDIT_INSTRUCTIONS.md](./AUDIT_INSTRUCTIONS.md) — what to focus on for a security audit and how to start.
 - [SKILLS.md](./SKILLS.md) — implementation nuances, gotchas, and reading order for working on this codebase.
 - [STYLE_GUIDE.md](./STYLE_GUIDE.md) — Solidity conventions and repo layout used across the V6 ecosystem.
-- [CHANGELOG.md](./CHANGELOG.md) — v5 → v6 ABI and behavior deltas.
+- [CHANGELOG.md](./CHANGELOG.md) - V5 to V6 ABI and behavior deltas.
 - [references/entrypoints.md](./references/entrypoints.md) — callable entrypoints by contract.
 - [references/types-errors-events.md](./references/types-errors-events.md) — packed metadata, errors, events, and hook return shapes.
 
@@ -72,6 +72,7 @@ The shortest reading path is:
 | `JBTerminalStore` | Shared accounting for balances, surplus, fees, and reclaim math. |
 | `JBDirectory` | Registry for controller and terminal routing. |
 | `JBProjects` | ERC-721 project registry and ownership surface. |
+| `JBERC20` | Cloneable project-token ERC-20 with Votes, Permit, ERC-1271, and active-vote total checkpoints. |
 | `JBPermissions` | Packed operator-permission registry. |
 | `JBPrices` | Price-feed routing used by terminals and integrations. |
 
@@ -81,6 +82,8 @@ The shortest reading path is:
 - Data hooks and cash-out hooks can change economics and side effects. They are part of the protocol surface.
 - Permission checks are not always against the project owner. Some flows are scoped to the token holder instead.
 - Preview and execution are intentionally close, but callers should still treat them as separate surfaces when hooks or routing can change behavior.
+- `JBERC20.getPastTotalSupply(...)` includes undelegated balances. Use `getPastTotalActiveVotes(...)` when an
+  integration must split value only among addresses with checkpointed voting power.
 
 ## Where state lives
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/core-v6",
-  "version": "0.0.82",
+  "version": "0.0.84",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -35,10 +35,10 @@
     "artifacts": "source ./.env && npx sphinx artifacts --org-id 'ea165b21-7cdc-4d7b-be59-ecdd4c26bee4' --project-name 'nana-core-v6'"
   },
   "dependencies": {
-    "@bananapus/permission-ids-v6": "^0.0.28",
+    "@bananapus/permission-ids-v6": "^0.0.30",
     "@chainlink/contracts": "1.5.0",
     "@openzeppelin/contracts": "5.6.1",
-    "@prb/math": "4.1.1",
+    "@prb/math": "4.1.2",
     "@uniswap/permit2": "github:Uniswap/permit2#cc56ad0f3439c502c246fc5cfcc3db92bb8b7219"
   },
   "devDependencies": {

package/references/entrypoints.md

@@ -21,7 +21,7 @@ The core Juicebox V6 protocol on EVM: a modular system for launching treasury-ba
 | `JBSplits` | Split configurations per project/ruleset/group. Packed storage for gas efficiency. |
 | `JBFundAccessLimits` | Payout limits and surplus allowances per project/ruleset/terminal/token. |
 | `JBPrices` | Append-only price feed registry with project-specific feeds, protocol defaults, inverse lookup, and backup feeds. |
-| `JBERC20` | Cloneable ERC-20 with Votes + Permit + ERC-1271. Controlled by `JBTokens` via `onlyTokens`. Deployed via `Clones.clone()`. |
+| `JBERC20` | Cloneable ERC-20 with Votes + Permit + ERC-1271 and active-vote total checkpoints. Controlled by `JBTokens` via `onlyTokens`. Deployed via `Clones.clone()`. |
 | `JBFeelessAddresses` | Static and hook-driven fee-exemption registry. |
 | `JBChainlinkV3PriceFeed` | Chainlink AggregatorV3 price feed with staleness threshold. Rejects negative/zero prices, incomplete rounds (`updatedAt == 0`), and stale answers carried from previous rounds (`answeredInRound < roundId`). |
 | `JBChainlinkV3SequencerPriceFeed` | L2 sequencer-aware Chainlink feed (Optimism/Arbitrum) with grace period after restart. Treats any non-zero sequencer answer as down (`answer != 0`). |
@@ -148,6 +148,13 @@ The core Juicebox V6 protocol on EVM: a modular system for launching treasury-ba
 | `totalCreditSupplyOf(uint256 projectId)` | Returns the internal credit supply for a project. |
 | `setTokenMetadataFor(uint256 projectId, string name, string symbol)` | Sets the name and symbol of a project's token. Controller-only. |
 
+### JBERC20
+
+| Function | What it does |
+|----------|--------------|
+| `getPastTotalActiveVotes(uint256 timepoint)` | Returns the total voting units delegated to nonzero delegates at a past block. Unlike `getPastTotalSupply`, this excludes undelegated balances such as AMM-held tokens with no delegate. |
+| `getTotalActiveVotes()` | Returns the current total voting units delegated to nonzero delegates. |
+
 ### JBSplits
 
 | Function | What it does |

package/references/types-errors-events.md

@@ -87,6 +87,8 @@ Use this file when you need deeper protocol reference material after the repo-lo
 - Credits are burned before ERC-20 tokens in `JBTokens.burnFrom()`
 - `JBRuleset.weight` is `uint112` with 18 decimals; `JBRuleset.metadata` is packed -- use `JBRulesetMetadataResolver` to unpack
 - `JBERC20` is cloned via `Clones.clone()` -- its constructor sets invalid name/symbol; real values set in `initialize()`
+- `JBERC20.getPastTotalSupply()` includes undelegated balances; `getPastTotalActiveVotes()` only counts balances whose
+  owner had a nonzero delegate at the queried block.
 - Fee is 2.5% (`FEE = 25` out of `MAX_FEE = 1000`)
 - Project #1 is the fee beneficiary project (receives all protocol fees)
 - **Fee-free cashout exemption is scoped to fee-free intra-terminal payout amounts.** `feeFreeSurplusOf[projectId][token]` accumulates the value of fee-free payouts. After any outflow (payouts, `useAllowanceOf`, non-zero-tax or feeless cashouts), the counter is capped at the remaining balance — non-fee-free funds leave first, preserving the fee-free counter. During cashout with `cashOutTaxRate=0`, the 2.5% fee applies only up to this surplus, then depletes. Once consumed, subsequent cashouts are fee-free again. Cleared on terminal migration. This prevents a round-trip fee bypass (intra-terminal payout → zero-tax cashout) while scoping fees precisely to the fee-free inflow.

package/src/JBController.sol

@@ -312,8 +312,7 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
     }
 
     /// @notice Converts a holder's internal project token credits into the project's ERC-20 representation,
-    /// transferring them to the beneficiary's wallet. Credits and the ERC-20 are equivalent project tokens — this
-    /// just
+    /// transferring them to the beneficiary's wallet. Credits and the ERC-20 are equivalent project tokens; this just
     /// makes them transferable/tradeable.
     /// @dev Can only be called by the credit holder or an operator with `CLAIM_TOKENS` permission.
     /// @param holder The address whose project token credits are being redeemed.
@@ -373,8 +372,7 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
         return TOKENS.deployERC20For({projectId: projectId, name: name, symbol: symbol, salt: saltHash});
     }
 
-    /// @notice When a project receives reserved tokens, if it has a terminal for the token, this is used to pay the
-    /// terminal.
+    /// @notice Pays a project's terminal with reserved tokens when the project has a terminal for that token.
     /// @dev Can only be called by this controller.
     /// @param terminal The terminal to pay.
     /// @param projectId The ID of the project to pay.
@@ -417,9 +415,7 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
         }
     }
 
-    /// @notice Creates a new Juicebox project in one transaction — mints the project NFT, queues initial rulesets,
-    /// and
-    /// configures terminals. This is the primary entry point for launching a project.
+    /// @notice Creates a Juicebox project in one transaction: mints the NFT, queues rulesets, and configures terminals.
     /// @dev Anyone can call this on behalf of any owner. This is a launch convenience, not owner authorization proof:
     /// frontends and operators must use the transaction sender, an explicit owner signature, or their own deployment
     /// flow to decide whether the owner intentionally launched a configuration. Each sub-operation (mint, queue,
@@ -745,8 +741,7 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
     }
 
     /// @notice Sets the name and symbol of a project's token.
-    /// @dev Can only be called by the project's owner or an address with the owner's permission to
-    /// `SET_TOKEN_METADATA`.
+    /// @dev Can only be called by the project's owner or an address with the owner's `SET_TOKEN_METADATA` permission.
     /// @param projectId The ID of the project to update the token for.
     /// @param name The new name.
     /// @param symbol The new symbol.
@@ -761,8 +756,7 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
 
     /// @notice Set a project's metadata URI.
     /// @dev This is typically an IPFS hash, optionally with an `ipfs://` prefix.
-    /// @dev Can only be called by the project's owner or an address with the owner's permission to
-    /// `SET_PROJECT_URI`.
+    /// @dev Can only be called by the project's owner or an address with the owner's `SET_PROJECT_URI` permission.
     /// @param projectId The ID of the project to set the metadata URI of.
     /// @param uri The metadata URI to set.
     function setUriOf(uint256 projectId, string calldata uri) external override {
@@ -1246,8 +1240,7 @@ contract JBController is JBPermissioned, ERC2771Context, IJBController, IJBMigra
     }
 
     /// @notice Sends pending reserved tokens to the project's reserved token splits.
-    /// @dev If the project has no reserved token splits, or if they don't add up to 100%, leftover tokens are sent to
-    /// the project's owner.
+    /// @dev If the project has no reserved token splits, or if they don't add up to 100%, leftovers go to the owner.
     /// @param projectId The ID of the project to send reserved tokens for.
     /// @return tokenCount The amount of reserved tokens minted and sent.
     function _sendReservedTokensToSplitsOf(uint256 projectId) internal returns (uint256 tokenCount) {

package/src/JBDirectory.sol

@@ -49,8 +49,7 @@ contract JBDirectory is JBPermissioned, Ownable, IJBDirectory {
     // --------------------- public stored properties -------------------- //
     //*********************************************************************//
 
-    /// @notice The specified project's controller, which dictates how its terminals interact with its tokens and
-    /// rulesets.
+    /// @notice The specified project's controller, which dictates how terminals interact with tokens and rulesets.
     /// @custom:param projectId The ID of the project to get the controller of.
     mapping(uint256 projectId => IERC165) public override controllerOf;
 
@@ -98,8 +97,7 @@ contract JBDirectory is JBPermissioned, Ownable, IJBDirectory {
     /// its tokens and rulesets. If the project already has a controller, this triggers a full migration lifecycle
     /// (`beforeReceiveMigrationFrom` → `migrate` → state update → `afterReceiveMigrationFrom`).
     /// @dev Can only be called if:
-    /// - The ruleset's metadata has `allowSetController` enabled, and the caller is the project's owner or has
-    /// `SET_CONTROLLER` permission.
+    /// - The ruleset metadata enables `allowSetController`, and the caller owns the project or has `SET_CONTROLLER`.
     /// - OR the caller `isAllowedToSetFirstController` and the project has no controller yet.
     /// @param projectId The ID of the project to set the controller for.
     /// @param controller The address of the controller to set.

package/src/JBERC20.sol

@@ -1,15 +1,18 @@
 // SPDX-License-Identifier: MIT
 pragma solidity 0.8.28;
 
+import {IERC1271} from "@openzeppelin/contracts/interfaces/IERC1271.sol";
 import {ERC20} from "@openzeppelin/contracts/token/ERC20/ERC20.sol";
 import {ERC20Permit, Nonces} from "@openzeppelin/contracts/token/ERC20/extensions/ERC20Permit.sol";
 import {ERC20Votes} from "@openzeppelin/contracts/token/ERC20/extensions/ERC20Votes.sol";
-import {ECDSA} from "@openzeppelin/contracts/utils/cryptography/ECDSA.sol";
-import {IERC1271} from "@openzeppelin/contracts/interfaces/IERC1271.sol";
 import {Nonces} from "@openzeppelin/contracts/utils/Nonces.sol";
+import {ECDSA} from "@openzeppelin/contracts/utils/cryptography/ECDSA.sol";
+import {SafeCast} from "@openzeppelin/contracts/utils/math/SafeCast.sol";
+import {Checkpoints} from "@openzeppelin/contracts/utils/structs/Checkpoints.sol";
 
 import {JBPermissionIds} from "@bananapus/permission-ids-v6/src/JBPermissionIds.sol";
 import {JBPermissioned} from "./abstract/JBPermissioned.sol";
+import {IJBActiveVotes} from "./interfaces/IJBActiveVotes.sol";
 import {IJBPermissions} from "./interfaces/IJBPermissions.sol";
 import {IJBProjects} from "./interfaces/IJBProjects.sol";
 import {IJBToken} from "./interfaces/IJBToken.sol";
@@ -20,7 +23,9 @@ import {IJBTokens} from "./interfaces/IJBTokens.sol";
 /// holders can claim their internal credits into this transferable token.
 /// @dev Only `JBTokens` can mint and burn. The project owner (via `SET_TOKEN_METADATA` permission) can rename the
 /// token. Supports ERC-1271 signature validation for smart-contract wallets.
-contract JBERC20 is ERC20Votes, ERC20Permit, JBPermissioned, IERC1271, IJBToken {
+contract JBERC20 is ERC20Votes, ERC20Permit, JBPermissioned, IERC1271, IJBActiveVotes, IJBToken {
+    using Checkpoints for Checkpoints.Trace208;
+
     //*********************************************************************//
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
@@ -50,6 +55,9 @@ contract JBERC20 is ERC20Votes, ERC20Permit, JBPermissioned, IERC1271, IJBToken
     // -------------------- private stored properties -------------------- //
     //*********************************************************************//
 
+    /// @notice The total voting units currently delegated to nonzero delegates.
+    Checkpoints.Trace208 private _activeSupplyCheckpoints;
+
     /// @notice The token's name.
     string private _name;
 
@@ -170,6 +178,19 @@ contract JBERC20 is ERC20Votes, ERC20Permit, JBPermissioned, IERC1271, IJBToken
         return super.decimals();
     }
 
+    /// @notice The total delegated voting units at a past block.
+    /// @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) public view override returns (uint256 activeVotes) {
+        activeVotes = _activeSupplyCheckpoints.upperLookupRecent(_validateTimepoint(timepoint));
+    }
+
+    /// @notice The current total delegated voting units.
+    /// @return activeVotes The current total voting units delegated to nonzero delegates.
+    function getTotalActiveVotes() public view override returns (uint256 activeVotes) {
+        activeVotes = _activeSupplyCheckpoints.latest();
+    }
+
     /// @notice The token's name, set during initialization.
     function name() public view virtual override returns (string memory) {
         return _name;
@@ -216,8 +237,45 @@ contract JBERC20 is ERC20Votes, ERC20Permit, JBPermissioned, IERC1271, IJBToken
     // ---------------------- internal transactions ---------------------- //
     //*********************************************************************//
 
+    /// @notice Track active-supply changes when an account moves between undelegated and delegated states.
+    function _delegate(address account, address delegatee) internal virtual override {
+        address oldDelegate = delegates(account);
+        uint256 votingUnits = _getVotingUnits(account);
+
+        super._delegate({account: account, delegatee: delegatee});
+
+        if (oldDelegate == address(0) && delegatee != address(0)) {
+            _updateActiveVotes({amount: votingUnits, increase: true});
+        } else if (oldDelegate != address(0) && delegatee == address(0)) {
+            _updateActiveVotes({amount: votingUnits, increase: false});
+        }
+    }
+
+    /// @notice Track active-supply changes when voting units move between delegated and undelegated accounts.
+    function _transferVotingUnits(address from, address to, uint256 amount) internal virtual override {
+        bool decreaseActiveVotes = from != address(0) && delegates(from) != address(0);
+        bool increaseActiveVotes = to != address(0) && delegates(to) != address(0);
+
+        super._transferVotingUnits({from: from, to: to, amount: amount});
+
+        if (decreaseActiveVotes == increaseActiveVotes) return;
+        _updateActiveVotes({amount: amount, increase: increaseActiveVotes});
+    }
+
     /// @notice Required override.
     function _update(address from, address to, uint256 value) internal virtual override(ERC20, ERC20Votes) {
         super._update({from: from, to: to, value: value});
     }
+
+    /// @notice Update the checkpointed total of delegated voting units.
+    /// @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) internal {
+        if (amount == 0) return;
+
+        uint256 updated =
+            increase ? _activeSupplyCheckpoints.latest() + amount : _activeSupplyCheckpoints.latest() - amount;
+
+        _activeSupplyCheckpoints.push({key: clock(), value: SafeCast.toUint208(updated)});
+    }
 }

package/src/JBMultiTerminal.sol

@@ -187,8 +187,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     // -------------------------- constructor ---------------------------- //
     //*********************************************************************//
 
-    /// @param feelessAddresses A contract that stores addresses that shouldn't incur fees when paid towards or
-    /// from.
+    /// @param feelessAddresses A contract that stores addresses that shouldn't incur fees on payments to or from them.
     /// @param permissions A contract storing permissions.
     /// @param projects A contract which mints ERC-721s that represent project ownership and transfers.
     /// @param splits A contract that stores splits for each project.
@@ -260,9 +259,8 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     /// @dev If `shouldReturnHeldFees` is true, the added amount offsets held fees proportionally.
     /// @param projectId The ID of the project to add funds to the balance of.
     /// @param token The terminal token being added (the ERC-20, or `JBConstants.NATIVE_TOKEN` for native).
-    /// @param amount The amount of the terminal `token` to add, as a fixed point number with the same number of
-    /// decimals as the token's accounting context. If `token` is the native token, this argument is ignored and
-    /// `msg.value` is used instead.
+    /// @param amount The amount of terminal `token` to add, as a fixed point number using the token accounting
+    /// context's decimals. If `token` is the native token, this argument is ignored and `msg.value` is used instead.
     /// @param shouldReturnHeldFees If true, return held fees proportional to the amount added.
     /// @param memo A memo to pass along to the emitted event.
     /// @param metadata Extra data to pass along to the emitted event.
@@ -304,8 +302,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     /// context. If fewer terminal tokens would be reclaimed, the cash out is reverted.
     /// @param beneficiary The address to send the reclaimed terminal tokens to, and to pass along to the ruleset's
     /// data hook and cash out hooks if applicable.
-    /// @param metadata Bytes to send along to the emitted event, as well as the data hook and cash out hooks if
-    /// applicable.
+    /// @param metadata Bytes to send to the emitted event, data hook, and cash out hooks, if applicable.
     /// @return reclaimAmount The amount of **terminal tokens** sent to `beneficiary` in exchange for the burned project
     /// tokens, as a fixed point number with the same number of decimals as the terminal token's accounting context.
     function cashOutTokensOf(
@@ -652,9 +649,8 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     /// `msg.value` is used in its place.
     /// @param beneficiary The address to mint project tokens to, and to pass along to the ruleset's data hook and pay
     /// hook if applicable.
-    /// @param minReturnedTokens The minimum number of project tokens the beneficiary must receive for the payment to
-    /// succeed, as a fixed point number with 18 decimals. If fewer project tokens would be minted, the payment is
-    /// reverted.
+    /// @param minReturnedTokens The minimum project tokens the beneficiary must receive for the payment to succeed, as
+    /// a fixed point number with 18 decimals. If fewer project tokens would be minted, the payment is reverted.
     /// @param memo A memo to pass along to the emitted event.
     /// @param metadata Bytes to pass along to the emitted event, as well as the data hook and pay hook if applicable.
     /// @return beneficiaryTokenCount The number of **project tokens** minted to `beneficiary`, as a fixed point number
@@ -780,18 +776,15 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     /// payout limit. Anyone can call this on behalf of any project.
     /// @dev If splits don't add up to 100%, the remainder goes to the project owner. A wildcard split (no hook,
     /// projectId, or beneficiary) sends its share to `msg.sender` — useful for incentivizing the call.
-    /// @dev Payouts to non-feeless addresses incur the 2.5% protocol fee. Projects whose terminal is feeless are
-    /// exempt.
+    /// @dev Payouts to non-feeless addresses incur the 2.5% protocol fee; feeless project terminals are exempt.
     /// @param projectId The ID of the project having its payouts sent.
     /// @param token The token to send.
     /// @param amount The total number of terminal tokens to send, as a fixed point number with the same number of
     /// decimals as the token's accounting context.
     /// @param currency The expected currency of the payouts. Must match the currency of one of the
     /// project's current ruleset's payout limits.
-    /// @param minTokensPaidOut The minimum number of terminal tokens that the `amount` should be worth (if expressed
-    /// in terms of the token's accounting context currency), as a fixed point number with the same number of decimals
-    /// as the token's accounting context. If the amount of tokens paid out would be less than this amount, the send is
-    /// reverted.
+    /// @param minTokensPaidOut The minimum terminal-token value of `amount`, if expressed in the token accounting
+    /// context currency. If the payout would be less than this amount, the send is reverted.
     /// @return amountPaidOut The total amount paid out.
     function sendPayoutsOf(
         uint256 projectId,
@@ -946,8 +939,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         });
     }
 
-    /// @notice Simulates a cash out without modifying state — use this to preview how many tokens a holder would
-    /// reclaim.
+    /// @notice Simulates a cash out without modifying state to preview how many tokens a holder would reclaim.
     /// @param holder The address cashing out tokens.
     /// @param projectId The ID of the project cashing out tokens.
     /// @param cashOutCount The number of project tokens to cash out.
@@ -988,9 +980,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         });
     }
 
-    /// @notice Simulates a payment without modifying state — use this to preview how many project tokens a payer
-    /// would
-    /// receive.
+    /// @notice Simulates a payment without modifying state to preview the project tokens a payer would receive.
     /// @param projectId The ID of the project to pay.
     /// @param token The token to pay with.
     /// @param amount The amount of tokens to pay.
@@ -1200,19 +1190,16 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
         }
     }
 
-    /// @notice Holders can cash out their tokens to reclaim some of a project's surplus, or to trigger rules determined
-    /// by
-    /// the project's current ruleset's data hook.
+    /// @notice Holders can cash out their tokens to reclaim some of a project's surplus, or to trigger rules
+    /// determined by the project's current ruleset's data hook.
     /// @dev Only a token holder or an operator with the `CASH_OUT_TOKENS` permission from that holder can cash out
-    /// those
-    /// tokens.
+    /// those tokens.
     /// @param holder The account cashing out tokens.
     /// @param projectId The ID of the project cashing out tokens.
     /// @param cashOutCount The number of project tokens to cash out, as a fixed point number with 18 decimals.
     /// @param tokenToReclaim The address of the token to reclaim.
     /// @param beneficiary The address to send the reclaimed terminal tokens to.
-    /// @param metadata Bytes to send along to the emitted event, as well as the data hook and cash out hook if
-    /// applicable.
+    /// @param metadata Bytes to send to the emitted event, data hook, and cash out hook, if applicable.
     /// @return reclaimAmount The number of terminal tokens reclaimed for the `beneficiary`, as a fixed point number
     /// with 18 decimals.
     function _cashOutTokensOf(
@@ -1500,8 +1487,8 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     /// @param metadata Bytes to send along to the emitted event and cash out hooks as applicable.
     /// @param ruleset The ruleset active during this cash out as a `JBRuleset` struct.
     /// @param cashOutTaxRate The cash out tax rate influencing the reclaim amount, out of
-    /// `JBConstants.MAX_CASH_OUT_TAX_RATE`. @param beneficiary The address which will receive any terminal tokens that
-    /// are cashed out.
+    /// `JBConstants.MAX_CASH_OUT_TAX_RATE`.
+    /// @param beneficiary The address which will receive any cashed out terminal tokens.
     /// @param specifications The hook specifications to fulfill.
     /// @return amountEligibleForFees The amount of funds which were allocated to cash out hooks and are eligible for
     /// fees.
@@ -1707,8 +1694,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     /// decimals as the token's accounting context. If this terminal's token is the native token, `amount` is ignored
     /// and `msg.value` is used in its place.
     /// @param payer The address making the payment.
-    /// @param beneficiary The address to mint tokens to, and pass along to the ruleset's data hook and pay hook if
-    /// applicable.
+    /// @param beneficiary The token recipient passed to the ruleset's data hook and pay hook, if applicable.
     /// @param memo A memo to pass along to the emitted event.
     /// @param metadata Bytes to send along to the emitted event, as well as the data hook and pay hook if applicable.
     function _pay(
@@ -2086,8 +2072,7 @@ contract JBMultiTerminal is JBPermissioned, ERC2771Context, IJBMultiTerminal {
     }
 
     /// @notice Allows a project to send out funds from its surplus up to the current surplus allowance.
-    /// @dev Only a project's owner or an operator with the `USE_ALLOWANCE` permission from that owner can use the
-    /// surplus allowance.
+    /// @dev Only a project's owner or an operator with the owner's `USE_ALLOWANCE` permission can use the allowance.
     /// @dev Incurs the protocol fee unless the caller is a feeless address.
     /// @param projectId The ID of the project to use the surplus allowance of.
     /// @param owner The project's owner.

package/src/JBPermissions.sol

@@ -30,9 +30,8 @@ contract JBPermissions is ERC2771Context, IJBPermissions {
     // ------------------------- public constants ------------------------ //
     //*********************************************************************//
 
-    /// @notice The project ID that acts as a wildcard — granting the operator permissions across all projects owned
-    /// by
-    /// the account. Setting permissions for project ID 0 is powerful and should be done carefully.
+    /// @notice Project ID 0 acts as a wildcard for permissions across all projects owned by the account.
+    /// @dev Setting permissions for project ID 0 is powerful and should be done carefully.
     uint256 public constant override WILDCARD_PROJECT_ID = 0;
 
     //*********************************************************************//
@@ -40,8 +39,7 @@ contract JBPermissions is ERC2771Context, IJBPermissions {
     //*********************************************************************//
 
     /// @notice The packed permission bitmap that an account has granted to an operator for a specific project.
-    /// @dev Each bit in the returned `uint256` corresponds to a permission ID (0–255). A `1` bit means that
-    /// permission
+    /// @dev Each bit in the returned `uint256` corresponds to a permission ID (0–255). A `1` bit means the permission
     /// is granted. See `JBPermissionIds` for the meaning of each ID.
     /// @custom:param operator The address of the operator.
     /// @custom:param account The address of the account operated on behalf of.

package/src/JBRulesets.sol

@@ -58,8 +58,7 @@ contract JBRulesets is JBControlled, IJBRulesets {
 
     /// @notice The ID of the ruleset with the latest start time for a specific project, whether the ruleset has been
     /// approved or not.
-    /// @dev If a project has multiple rulesets queued, the `latestRulesetIdOf` will be the last one. This is the
-    /// "changeable" cycle.
+    /// @dev If a project has multiple rulesets queued, `latestRulesetIdOf` is the last "changeable" cycle.
     /// @custom:param projectId The ID of the project to get the latest ruleset ID of.
     /// @return latestRulesetIdOf The `rulesetId` of the project's latest ruleset.
     mapping(uint256 projectId => uint256) public override latestRulesetIdOf;
@@ -218,9 +217,7 @@ contract JBRulesets is JBControlled, IJBRulesets {
 
     /// @notice Cache the value of the ruleset weight for a specific ruleset.
     /// @dev The caller should pass the ruleset ID that `currentOf()` actually uses. When a queued ruleset is rejected
-    /// by an approval hook, `currentOf()` falls back to the base ruleset — callers should pass that base ruleset's
-    /// ID,
-    /// not the rejected latest.
+    /// by an approval hook, `currentOf()` falls back to the base ruleset, not the rejected latest.
     /// @param projectId The ID of the project having its ruleset weight cached.
     /// @param rulesetId The ID of the ruleset to update the cache for.
     function updateRulesetWeightCache(uint256 projectId, uint256 rulesetId) external override {
@@ -574,8 +571,7 @@ contract JBRulesets is JBControlled, IJBRulesets {
     /// @notice The date that is the nearest multiple of the base ruleset's duration from the start of the next cycle.
     /// @param baseRulesetStart The start time of the base ruleset.
     /// @param baseRulesetDuration The duration of the base ruleset.
-    /// @param mustStartAtOrAfter The earliest time the next ruleset can start. The ruleset cannot start before this
-    /// timestamp.
+    /// @param mustStartAtOrAfter The earliest timestamp the next ruleset can start at.
     /// @return start The next start time.
     function deriveStartFrom(
         uint256 baseRulesetStart,
@@ -703,8 +699,7 @@ contract JBRulesets is JBControlled, IJBRulesets {
     /// @param projectId The ID of the project to update the latest ruleset for.
     /// @param rulesetId The timestamp of when the ruleset was queued.
     /// @param weight The weight to store in the queued ruleset.
-    /// @param mustStartAtOrAfter The earliest time the ruleset can start. The ruleset cannot start before this
-    /// timestamp.
+    /// @param mustStartAtOrAfter The earliest timestamp the ruleset can start at.
     function _configureIntrinsicPropertiesFor(
         uint256 projectId,
         uint256 rulesetId,
@@ -791,8 +786,7 @@ contract JBRulesets is JBControlled, IJBRulesets {
     /// @param projectId The ID of the project to initialize the ruleset for.
     /// @param baseRuleset The ruleset struct to base the newly initialized one on.
     /// @param rulesetId The `rulesetId` for the ruleset to initialize.
-    /// @param mustStartAtOrAfter The earliest time the ruleset can start. The ruleset cannot start before this
-    /// timestamp.
+    /// @param mustStartAtOrAfter The earliest timestamp the ruleset can start at.
     /// @param weight The weight to give the newly initialized ruleset.
     function _initializeRulesetFor(
         uint256 projectId,

package/src/JBTerminalStore.sol

@@ -121,8 +121,7 @@ contract JBTerminalStore is IJBTerminalStore {
     /// @notice The currency-denominated amount of funds that a project has already paid out from its payout limit
     /// during the current ruleset for each terminal, in terms of the payout limit's currency.
     /// @dev Increases as projects pay out funds.
-    /// @dev The used payout limit is represented as a fixed point number with the same amount of decimals as the
-    /// terminal it applies to.
+    /// @dev The used payout limit is a fixed point number with the same decimals as the terminal it applies to.
     /// @custom:param terminal The terminal the payout limit applies to.
     /// @custom:param projectId The ID of the project to get the used payout limit of.
     /// @custom:param token The token the payout limit applies to in the terminal.
@@ -141,8 +140,7 @@ contract JBTerminalStore is IJBTerminalStore {
     /// @notice The currency-denominated amounts of funds that a project has used from its surplus allowance during the
     /// current ruleset for each terminal, in terms of the surplus allowance's currency.
     /// @dev Increases as projects use their allowance.
-    /// @dev The used surplus allowance is represented as a fixed point number with the same amount of decimals as the
-    /// terminal it applies to.
+    /// @dev The used surplus allowance is a fixed point number with the same decimals as the terminal it applies to.
     /// @dev Surplus allowance usage is keyed by `ruleset.id`, not cycle number. Implicit cycle progression
     /// (duration-based auto-cycling) does not reset allowance — this is by design. Projects must queue a new ruleset
     /// to get a fresh allowance.
@@ -414,8 +412,7 @@ contract JBTerminalStore is IJBTerminalStore {
         }
     }
 
-    /// @notice Records a payout — decrements the project's balance and enforces the payout limit. Called by the
-    /// terminal during `sendPayoutsOf`.
+    /// @notice Records a payout during `sendPayoutsOf`, decrementing balance and enforcing the payout limit.
     /// @dev Reverts if the total payouts for this cycle would exceed the ruleset's payout limit. The balance is
     /// decremented before validation (safe because the entire tx reverts atomically on failure).
     /// @param projectId The ID of the project that is paying out funds.
@@ -812,8 +809,7 @@ contract JBTerminalStore is IJBTerminalStore {
     }
 
     /// @notice Simulates a payment without modifying state.
-    /// @dev Invokes data hooks if configured. Returns the same token count and hook specifications that
-    /// `recordPaymentFrom` would produce.
+    /// @dev Invokes data hooks if configured. Returns what `recordPaymentFrom` would produce.
     /// @param terminal The terminal to simulate the payment from.
     /// @param payer The address of the payer.
     /// @param amount The amount to pay.
@@ -1208,8 +1204,7 @@ contract JBTerminalStore is IJBTerminalStore {
         });
     }
 
-    /// @notice Gets the current surplus amount for a project across specified terminals and tokens, using a
-    /// pre-fetched ruleset.
+    /// @notice Gets a project's current surplus across specified terminals and tokens using a pre-fetched ruleset.
     /// @dev Use this overload when the caller already has the current ruleset to avoid a redundant
     /// `RULESETS.currentOf()` call.
     /// @param projectId The ID of the project to get surplus for.

package/src/abstract/JBPermissioned.sol

@@ -85,9 +85,7 @@ abstract contract JBPermissioned is Context, IJBPermissioned {
         ) revert JBPermissioned_Unauthorized(account, sender, projectId, permissionId);
     }
 
-    /// @notice If the 'alsoGrantAccessIf' condition is truthy, proceed. Otherwise, require the message sender to be the
-    /// account or
-    /// have the relevant permission.
+    /// @notice If `alsoGrantAccessIf` is false, require the message sender to be the account or have permission.
     /// @param account The account to allow.
     /// @param projectId The project ID to check the permission under.
     /// @param permissionId The required permission ID. The operator must have this permission within the specified

package/src/interfaces/IJBActiveVotes.sol

@@ -0,0 +1,14 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.0;
+
+/// @notice Provides checkpointed totals for voting units delegated to nonzero delegates.
+interface IJBActiveVotes {
+    /// @notice The total delegated voting units at a past timepoint.
+    /// @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 returns (uint256 activeVotes);
+
+    /// @notice The current total delegated voting units.
+    /// @return activeVotes The current total voting units delegated to nonzero delegates.
+    function getTotalActiveVotes() external view returns (uint256 activeVotes);
+}

package/src/interfaces/IJBCashOutTerminal.sol

@@ -75,8 +75,7 @@ interface IJBCashOutTerminal is IJBTerminal {
             JBCashOutHookSpecification[] memory hookSpecifications
         );
 
-    /// @notice Burn a holder's project tokens to reclaim a proportional share of the project's surplus (paid out as a
-    /// terminal token).
+    /// @notice Burn a holder's project tokens to reclaim a proportional share of surplus in a terminal token.
     /// @param holder The address whose project tokens are being burned.
     /// @param projectId The ID of the project whose project tokens are being burned.
     /// @param cashOutCount The number of project tokens to burn.

package/src/interfaces/IJBController.sol

@@ -329,8 +329,8 @@ interface IJBController is IERC165, IJBProjectUriRegistry, IJBDirectoryAccessCon
     /// @notice Mints new project tokens (or credits) to a beneficiary, optionally reserving a portion for the ruleset's
     /// reserved splits.
     /// @param projectId The ID of the project whose project tokens are being minted.
-    /// @param tokenCount The total number of project tokens to mint (the beneficiary's share plus the reserved share if
-    /// `useReservedPercent` is true).
+    /// @param tokenCount The total number of project tokens to mint, including reserved tokens if
+    /// `useReservedPercent` is true.
     /// @param beneficiary The address that receives the non-reserved portion of the minted project tokens.
     /// @param memo A memo to pass along to the emitted event.
     /// @param useReservedPercent Whether to apply the ruleset's reserved percent.

package/src/interfaces/IJBFeelessAddresses.sol

@@ -13,8 +13,7 @@ interface IJBFeelessAddresses {
     /// @param caller The address that set the feeless status.
     event SetFeelessAddress(uint256 indexed projectId, address indexed addr, bool indexed isFeeless, address caller);
 
-    /// @notice The optional hook (set by the owner) that can grant feeless status with arbitrary logic. Set to the
-    /// zero address to disable.
+    /// @notice The optional owner-set hook that can grant feeless status. Set to the zero address to disable.
     /// @param hook The new feeless hook. The zero address disables hook consultation.
     /// @param caller The address that set the hook.
     event SetFeelessHook(IJBFeelessHook indexed hook, address caller);

package/src/interfaces/IJBFeelessHook.sol

@@ -17,8 +17,8 @@ interface IJBFeelessHook is IERC165 {
     /// the terminal (so it gets fee-free cash-outs when zapping, but does NOT get feeless status when it merely
     /// appears as a split recipient of someone else's payout).
     /// @param projectId The ID of the project the fee would be charged on behalf of.
-    /// @param addr The address being checked (typically a payout recipient, surplus allowance beneficiary, or
-    /// cash-out beneficiary).
+    /// @param addr The address being checked, typically a payout recipient, surplus allowance beneficiary, or cash-out
+    /// beneficiary.
     /// @param caller The outer caller that initiated the terminal operation, or `address(0)` if not provided.
     /// @return A flag indicating whether the address is feeless for the project under the hook's custom logic.
     function isFeeless(uint256 projectId, address addr, address caller) external view returns (bool);

package/src/structs/JBAccountingContext.sol

@@ -1,8 +1,7 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.0;
 
-/// @notice Describes how a terminal accounts for a specific token — its address, decimal precision, and which
-/// currency
+/// @notice Describes how a terminal accounts for a specific token — its address, decimal precision, and the currency
 /// it's priced in. Used when recording payments, payouts, and cash outs to ensure correct fixed-point arithmetic.
 /// @custom:member token The token address (use `JBConstants.NATIVE_TOKEN` for ETH).
 /// @custom:member decimals The number of decimals for this token's fixed-point amounts (e.g. 18 for ETH, 6 for USDC).

package/src/structs/JBAfterCashOutRecordedContext.sol

@@ -9,8 +9,7 @@ import {JBTokenAmount} from "./JBTokenAmount.sol";
 /// @custom:member cashOutCount The number of project tokens to cash out.
 /// @custom:member cashOutTaxRate The current ruleset's cash out tax rate, out of
 /// `JBConstants.MAX_CASH_OUT_TAX_RATE`.
-/// @custom:member reclaimedAmount The token amount reclaimed from the project's terminal balance. Includes the
-/// token
+/// @custom:member reclaimedAmount The token amount reclaimed from the project's terminal balance. Includes the token
 /// reclaimed, the value, the number of decimals included, and the currency of the amount.
 /// @custom:member forwardedAmount The token amount forwarded to the cash out hook. Includes the token
 /// forwarded, the value, the number of decimals included, and the currency of the amount.

package/src/structs/JBCashOutHookSpecification.sol

@@ -3,8 +3,7 @@ pragma solidity ^0.8.0;
 
 import {IJBCashOutHook} from "../interfaces/IJBCashOutHook.sol";
 
-/// @notice A cash out hook specification sent from the ruleset's data hook back to the terminal. This specification is
-/// fulfilled by the terminal.
+/// @notice A cash out hook specification sent from the ruleset's data hook back to the terminal for fulfillment.
 /// @custom:member hook The cash out hook to use when fulfilling this specification.
 /// @custom:member noop A flag indicating if the hook callback should be skipped.
 /// @custom:member amount The amount to send to the hook.

package/src/structs/JBPayHookSpecification.sol

@@ -3,8 +3,7 @@ pragma solidity ^0.8.0;
 
 import {IJBPayHook} from "../interfaces/IJBPayHook.sol";
 
-/// @notice A pay hook specification sent from the ruleset's data hook back to the terminal. This specification is
-/// fulfilled by the terminal.
+/// @notice A pay hook specification sent from the ruleset's data hook back to the terminal for fulfillment.
 /// @custom:member hook The pay hook to use when fulfilling this specification.
 /// @custom:member noop A flag indicating if the hook callback should be skipped.
 /// @custom:member amount The amount to send to the hook.

package/src/structs/JBSplit.sol

@@ -15,8 +15,7 @@ import {IJBSplitHook} from "./../interfaces/IJBSplitHook.sol";
 /// `beneficiary`.
 /// @custom:member percent The percent of the total token amount that this split sends. This number is out of
 /// `JBConstants.SPLITS_TOTAL_PERCENT`.
-/// @custom:member projectId The ID of a project to `pay`, if applicable. Resulting tokens will be routed to the
-/// `beneficiary`.
+/// @custom:member projectId The ID of a project to `pay`, if applicable. Resulting tokens are routed to `beneficiary`.
 /// @custom:member beneficiary Receives this split's tokens if the `hook` and `projectId` are zero. If the `projectId`
 /// is specified, the `beneficiary` receives any project tokens minted by this split. If `beneficiary` is `address(0)`,
 /// the application processing the split decides on the recipient. For example, the terminal uses `msg.sender` for