@bananapus/core-v6 0.0.33 → 0.0.35

package/USER_JOURNEYS.md

@@ -1,6 +1,12 @@
 # User Journeys
 
-## Who This Repo Serves
+## Repo Purpose
+
+This repo is the canonical Juicebox V6 runtime surface.
+It owns project identity, rulesets, terminal execution, treasury accounting, permissions, price feeds, and migration
+paths. Most other V6 repos wrap or extend this behavior rather than replacing it.
+
+## Primary Actors
 
 - founders launching and evolving Juicebox projects
 - supporters paying projects in the asset a terminal accepts
@@ -8,109 +14,203 @@
 - operators managing permissions, splits, fund access limits, and rulesets
 - integrators wiring hooks, terminals, price feeds, and migrations into the canonical protocol surface
 
+## Key Surfaces
+
+- `JBController`: project launch, ruleset queueing, token setup, splits, and controller migration
+- `JBMultiTerminal`: pay, payout, allowance, preview, and cash-out entrypoint
+- `JBTerminalStore`: balance, surplus, fee, and reclaim accounting
+- `JBDirectory`: controller and terminal routing
+- `JBPermissions`: packed operator-permission registry
+- `JBProjects`, `JBRulesets`, `JBPrices`, `JBFundAccessLimits`, `JBSplits`, `JBTokens`: core state and helper surfaces
+
 ## Journey 1: Launch A Project With The Right Initial Shape
 
-**Starting state:** you know who should own the project, which terminals it should use, and what the first ruleset should allow.
+**Actor:** founder, deployer, or protocol integrator.
 
-**Success:** the project NFT exists, the initial ruleset is active, accepted terminals are installed, and downstream hooks or splits can begin working immediately.
+**Intent:** create a project with the right owner, terminal, ruleset, and hook assumptions from block zero.
 
-**Flow**
+**Preconditions**
+- the team knows who should own the project, which terminals it should use, and what the first ruleset should allow
+
+**Main Flow**
 1. Call `JBController.launchProjectFor(...)` with the owner, URI, ruleset config, terminal configs, and any split or hook metadata.
 2. `JBProjects` mints the project NFT, `JBDirectory` records controller and terminal routing, and `JBRulesets` stores the first ruleset.
 3. If the project wants ERC-20 tokens, reserved-rate behavior, or hook-driven behavior, that configuration is committed at launch instead of being inferred later.
 4. The project can now accept payments and queue future rulesets without changing project identity.
 
-**Failure cases that matter:** mismatched accounting contexts, wrong terminals for the target asset, invalid hook metadata, and launching with permissions or ownership assumptions that cannot be repaired cleanly later.
+**Failure Modes**
+- accounting contexts do not match the intended terminal asset
+- hook metadata or split assumptions are invalid at launch
+- ownership or permission assumptions are wrong and expensive to repair later
+
+**Postconditions**
+- the project NFT exists, the initial ruleset is active, accepted terminals are installed, and downstream hooks or splits can begin working immediately
 
 ## Journey 2: Accept A Payment And Issue The Right Token Exposure
 
-**Starting state:** the project has an active ruleset and a terminal that accepts the payer's asset.
+**Actor:** payer or integration paying on a user's behalf.
+
+**Intent:** settle a payment through the canonical terminal path and issue the correct token exposure.
 
-**Success:** treasury balances increase, hooks run in the right order, and the beneficiary receives credits or ERC-20 tokens consistent with the ruleset.
+**Preconditions**
+- the project has an active ruleset and a terminal that accepts the payer's asset
 
-**Flow**
+**Main Flow**
 1. A payer calls `pay(...)` on `JBMultiTerminal`.
 2. The terminal validates the accounting context, records funds, and asks `JBTerminalStore` to derive issuance from the active ruleset.
 3. `JBController` and `JBTokens` decide whether the beneficiary gets project token credits, ERC-20s, or no issuance because weight is zero.
 4. Any configured pay hooks or data hooks run around the accounting path.
 
-**Edge conditions that change user experience:** paused payments, custom hook side effects, fee-on-transfer tokens, unsupported price feeds, zero-weight rulesets, and permit-based flows.
+**Failure Modes**
+- payments are paused or the token is unsupported for the target accounting context
+- fee-on-transfer behavior or price-feed assumptions break the intended issuance path
+- hooks add side effects the payer or integrator did not account for
+
+**Postconditions**
+- treasury balances increase, hooks run in the right order, and the beneficiary receives credits or ERC-20 tokens consistent with the ruleset
 
 ## Journey 3: Turn Credits Into ERC-20 Tokens Once A Project Wants A Transferable Token
 
-**Starting state:** users already have project token credits and the project now wants an ERC-20 representation.
+**Actor:** holder or operator acting for a holder.
+
+**Intent:** convert non-transferable project credits into ERC-20 balances once the project exposes a token.
 
-**Success:** the project deploys or installs its ERC-20 token and holders can claim credits into transferable balances.
+**Preconditions**
+- users already have project token credits
+- the project now wants an ERC-20 representation
 
-**Flow**
+**Main Flow**
 1. Deploy or set the project's ERC-20 token through `JBController`.
 2. Holders or operators call `claimTokensFor(...)` to convert credits into ERC-20 balances for a beneficiary.
 3. Future issuance can continue using the same project identity while users now interact with a standard token surface.
 
+**Failure Modes**
+- the wrong token is installed for the project
+- integrations assume credits are automatically ERC-20 balances after token installation
+
+**Postconditions**
+- the project deploys or installs its ERC-20 token and holders can claim credits into transferable balances
+
 ## Journey 4: Distribute Treasury Funds Through Governed Paths
 
-**Starting state:** the project has terminal balances and the owner wants payouts or allowance-based withdrawals.
+**Actor:** owner or authorized operator.
+
+**Intent:** move value out of the treasury through configured payouts or allowance surfaces.
 
-**Success:** treasury value leaves only through configured limits, recipients, and fee logic instead of arbitrary admin withdrawals.
+**Preconditions**
+- the project has terminal balances
+- the caller is allowed to use payout or allowance paths
 
-**Flow**
+**Main Flow**
 1. Authorized actors call payout or allowance surfaces on the terminal.
 2. `JBFundAccessLimits` bounds how much may leave for the current ruleset cycle.
 3. `JBSplits` fans value out to beneficiaries, projects, hooks, or fee recipients as configured.
 4. `JBTerminalStore` updates balances and fee accounting so later previews and cash outs remain consistent.
 
-**Failure cases that matter:** stale split expectations, exceeding access limits, downstream hook failures, and assuming allowance withdrawals behave like payouts when fee treatment differs.
+**Failure Modes**
+- splits or access limits no longer match operator expectations
+- downstream hook execution fails during payout fanout
+- operators assume allowance withdrawals behave exactly like payouts when fee treatment differs
+
+**Postconditions**
+- treasury value leaves only through configured limits, recipients, and fee logic instead of arbitrary admin withdrawals
 
 ## Journey 5: Let Holders Cash Out Against Surplus
 
-**Starting state:** a holder owns project token exposure and the project has reclaimable surplus in some terminal.
+**Actor:** holder or integrator acting for a holder.
 
-**Success:** the holder burns the intended amount of token exposure and receives the correct reclaim amount under the current ruleset.
+**Intent:** exit project-token exposure against available terminal surplus.
 
-**Flow**
+**Preconditions**
+- a holder owns project token exposure
+- the project has reclaimable surplus in some terminal
+
+**Main Flow**
 1. The holder calls `cashOutTokensOf(...)` on the relevant terminal.
 2. `JBTerminalStore` calculates reclaim value using surplus, outstanding token supply, cash-out tax rate, and any pending reserved token effects.
 3. Cash-out hooks can modify behavior or side effects, but the core accounting remains anchored in the terminal store.
 4. Tokens burn and value exits the treasury through the terminal that actually held the asset.
 
-**Edge conditions that matter:** fee-free addresses, custom cash-out hooks, preview-versus-execution drift under volatile routing, and multi-terminal surplus that users may misread as single-pool liquidity.
+**Failure Modes**
+- fee-free or custom hook paths produce different outcomes than the holder expected
+- preview-versus-execution drift appears under volatile routing or multi-terminal liquidity
+- users misread multi-terminal surplus as one homogeneous pool
+
+**Postconditions**
+- the holder burns the intended amount of token exposure and receives the correct reclaim amount under the current ruleset
 
 ## Journey 6: Queue New Rulesets Without Migrating The Project
 
-**Starting state:** the project is live and future economics need to change.
+**Actor:** owner or authorized operator.
+
+**Intent:** change future project economics without changing the project's identity or existing balances.
 
-**Success:** the next ruleset activates on schedule while the project keeps the same identity, treasury, and downstream integrations.
+**Preconditions**
+- the project is live and future economics need to change
 
-**Flow**
+**Main Flow**
 1. The owner or an operator with the right permission queues one or more new rulesets through `JBController`.
 2. `JBRulesets` stores the proposed future configuration and any approval hook requirements.
 3. When the active duration elapses, the next approved ruleset becomes live and future pays, payouts, and cash outs follow the new terms.
 4. Existing balances and token history remain intact because only future behavior changed.
 
-**Failure cases that matter:** forgetting approval hooks, queueing incompatible metadata for installed hooks, and assuming a ruleset change can retroactively repair prior accounting.
+**Failure Modes**
+- approval-hook requirements are forgotten or misunderstood
+- queued metadata is incompatible with installed hooks
+- teams assume a ruleset change can retroactively fix prior accounting
+
+**Postconditions**
+- the next ruleset activates on schedule while the project keeps the same identity, treasury, and downstream integrations
 
 ## Journey 7: Migrate A Project To New Terminal Or Controller Surfaces Deliberately
 
-**Starting state:** the project needs to move to a new terminal or controller path without pretending historical balances and routing do not exist.
+**Actor:** owner or migration operator.
+
+**Intent:** move a live project to new terminal or controller surfaces without corrupting balances, permissions, or routing history.
 
-**Success:** migration uses the protocol's explicit surfaces so balances, permissions, and future routing stay coherent.
+**Preconditions**
+- the project needs to move to a new terminal or controller path
+- the destination surface is understood and intended
 
-**Flow**
+**Main Flow**
 1. Confirm the active ruleset permits migration and the destination surface is the intended successor.
 2. Use `JBController.migrate(...)` and the terminal-store migration paths instead of manually repointing addresses.
 3. Recheck directory routing and accepted accounting contexts after migration completes.
 
+**Failure Modes**
+- migration targets are wrong or only partially configured
+- operators manually repoint routing without using the protocol's migration surfaces
+
+**Postconditions**
+- balances, permissions, and future routing stay coherent after migration
+
 ## Journey 8: Hand Off Authority Without Handing Out Root Access
 
-**Starting state:** the project owner wants operators, delegates, or automation to manage only specific surfaces.
+**Actor:** project owner.
+
+**Intent:** delegate project operations narrowly instead of transferring blanket control.
 
-**Success:** permissions are narrow, auditable, and scoped to the actions the operator actually needs.
+**Preconditions**
+- the owner wants operators, delegates, or automation to manage only specific surfaces
 
-**Flow**
+**Main Flow**
 1. The owner configures operator permissions in `JBPermissions`.
 2. Downstream calls check those packed permission bits instead of assuming project ownership.
 3. Integrations such as ownable wrappers, hook deployers, and router registries can now respect project-scoped delegation without custom ACL logic.
 
+**Failure Modes**
+- operators receive permissions broader than they need
+- auditors assume downstream access still depends only on project ownership
+
+**Postconditions**
+- permissions are narrow, auditable, and scoped to the actions the operator actually needs
+
+## Trust Boundaries
+
+- `JBTerminalStore` is the accounting truth for balances, surplus, fees, and reclaim behavior
+- hooks, approval hooks, pay hooks, and cash-out hooks are trusted extension surfaces, not cosmetic plugins
+- price feeds and directory routing are critical external-context surfaces inherited by many downstream repos
+
 ## Hand-Offs
 
 - Use [nana-permission-ids-v6](../nana-permission-ids-v6/USER_JOURNEYS.md) for the shared permission vocabulary that downstream repos import.

package/foundry.toml

@@ -16,6 +16,8 @@ fail_on_revert = false
 [rpc_endpoints]
 ethereum = "${RPC_ETHEREUM_MAINNET}"
 
+[lint]
+exclude_lints = ["pascal-case-struct", "mixed-case-variable"]
 [fmt]
 number_underscore = "thousands"
 multiline_func_header = "all"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/core-v6",
-  "version": "0.0.33",
+  "version": "0.0.35",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -26,7 +26,7 @@
     "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.15",
+    "@bananapus/permission-ids-v6": "^0.0.17",
     "@chainlink/contracts": "^1.5.0",
     "@openzeppelin/contracts": "^5.6.1",
     "@prb/math": "^4.1.1",

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` | Price feed registry with project-specific and protocol-wide default feeds. Immutable once set. |
-| `JBERC20` | Cloneable ERC-20 with Votes + Permit. Owned by `JBTokens`. Deployed via `Clones.clone()`. |
+| `JBERC20` | Cloneable ERC-20 with Votes + Permit + ERC-1271. Controlled by `JBTokens` via `onlyTokens`. Deployed via `Clones.clone()`. |
 | `JBFeelessAddresses` | Allowlist for fee-exempt addresses. |
 | `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`). |

package/script/Deploy.s.sol

@@ -85,7 +85,8 @@ contract Deploy is Script, Sphinx {
             trustedForwarder: TRUSTED_FORWARDER
         });
         JBTokens tokens = new JBTokens{salt: keccak256(abi.encode(CORE_DEPLOYMENT_NONCE))}({
-            directory: directory, token: new JBERC20{salt: keccak256(abi.encode(CORE_DEPLOYMENT_NONCE))}()
+            directory: directory,
+            token: new JBERC20{salt: keccak256(abi.encode(CORE_DEPLOYMENT_NONCE))}(permissions, projects)
         });
 
         new JBFundAccessLimits{salt: keccak256(abi.encode(CORE_DEPLOYMENT_NONCE))}(directory);

package/src/JBERC20.sol

@@ -1,27 +1,49 @@
 // SPDX-License-Identifier: MIT
 pragma solidity 0.8.28;
 
-import {Ownable} from "@openzeppelin/contracts/access/Ownable.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 {JBPermissionIds} from "@bananapus/permission-ids-v6/src/JBPermissionIds.sol";
+import {JBPermissioned} from "./abstract/JBPermissioned.sol";
+import {IJBPermissions} from "./interfaces/IJBPermissions.sol";
+import {IJBProjects} from "./interfaces/IJBProjects.sol";
 import {IJBToken} from "./interfaces/IJBToken.sol";
+import {IJBTokens} from "./interfaces/IJBTokens.sol";
 
 /// @notice An ERC-20 token that can be used by a project in `JBTokens` and `JBController`.
 /// @dev By default, a project uses "credits" to track balances. Once a project sets their `IJBToken` using
 /// `JBController.deployERC20For(...)` or `JBController.setTokenFor(...)`, credits can be redeemed to claim tokens.
 /// @dev `JBController.deployERC20For(...)` deploys a `JBERC20` contract and sets it as the project's token.
-contract JBERC20 is ERC20Votes, ERC20Permit, Ownable, IJBToken {
+contract JBERC20 is ERC20Votes, ERC20Permit, JBPermissioned, IERC1271, IJBToken {
     //*********************************************************************//
     // --------------------------- custom errors ------------------------- //
     //*********************************************************************//
 
     error JBERC20_AlreadyInitialized();
+    error JBERC20_Unauthorized();
 
     //*********************************************************************//
-    // --------------------- internal stored properties ------------------ //
+    // --------------- public immutable stored properties ---------------- //
+    //*********************************************************************//
+
+    /// @notice The projects contract used to resolve project ownership.
+    IJBProjects public immutable PROJECTS;
+
+    //*********************************************************************//
+    // --------------------- public stored properties -------------------- //
+    //*********************************************************************//
+
+    /// @notice The JBTokens contract that owns this token.
+    /// @dev Set via `initialize` because JBERC20 is deployed before JBTokens (circular dependency).
+    IJBTokens public TOKENS;
+
+    //*********************************************************************//
+    // -------------------- private stored properties -------------------- //
     //*********************************************************************//
 
     /// @notice The token's name.
@@ -38,8 +60,29 @@ contract JBERC20 is ERC20Votes, ERC20Permit, Ownable, IJBToken {
 
     /// @dev Set `_name` on the implementation contract to prevent it from being initialized directly.
     /// Clones start with empty `_name`, so `initialize(...)` works only on clones.
-    constructor() Ownable(address(this)) ERC20("invalid", "invalid") ERC20Permit("JBToken") {
+    /// @param permissions The permissions contract.
+    /// @param projects The projects contract.
+    constructor(
+        IJBPermissions permissions,
+        IJBProjects projects
+    )
+        ERC20("invalid", "invalid")
+        ERC20Permit("JBToken")
+        JBPermissioned(permissions)
+    {
         _name = "invalid";
+        PROJECTS = projects;
+    }
+
+    //*********************************************************************//
+    // --------------------------- modifiers ---------------------------- //
+    //*********************************************************************//
+
+    /// @notice Only the JBTokens contract can call this function.
+    // forge-lint: disable-next-line(unwrapped-modifier-logic)
+    modifier onlyTokens() {
+        if (msg.sender != address(TOKENS)) revert JBERC20_Unauthorized();
+        _;
     }
 
     //*********************************************************************//
@@ -47,51 +90,32 @@ contract JBERC20 is ERC20Votes, ERC20Permit, Ownable, IJBToken {
     //*********************************************************************//
 
     /// @notice Burn some outstanding tokens.
-    /// @dev Can only be called by this contract's owner.
+    /// @dev Can only be called by the JBTokens contract.
     /// @param account The address to burn tokens from.
     /// @param amount The amount of tokens to burn, as a fixed point number with 18 decimals.
-    function burn(address account, uint256 amount) external override onlyOwner {
+    function burn(address account, uint256 amount) external override onlyTokens {
         return _burn({account: account, value: amount});
     }
 
     /// @notice Mints more of this token.
-    /// @dev Can only be called by this contract's owner.
+    /// @dev Can only be called by the JBTokens contract.
     /// @param account The address to mint the new tokens to.
     /// @param amount The amount of tokens to mint, as a fixed point number with 18 decimals.
-    function mint(address account, uint256 amount) external override onlyOwner {
+    function mint(address account, uint256 amount) external override onlyTokens {
         return _mint({account: account, value: amount});
     }
 
     /// @notice Sets the token's name and symbol.
-    /// @dev Can only be called by this contract's owner.
+    /// @dev Can only be called by the JBTokens contract.
     /// @param name_ The new name.
     /// @param symbol_ The new symbol.
-    function setMetadata(string memory name_, string memory symbol_) external override onlyOwner {
-        _name = name_;
-        _symbol = symbol_;
-    }
-
-    //*********************************************************************//
-    // ----------------------- public transactions ----------------------- //
-    //*********************************************************************//
-
-    /// @notice Initializes the token.
-    /// @param name_ The token's name.
-    /// @param symbol_ The token's symbol.
-    /// @param owner The token contract's owner.
-    function initialize(string memory name_, string memory symbol_, address owner) public override {
-        // Prevent re-initialization by reverting if a name is already set or if the provided name is empty.
-        if (bytes(_name).length != 0 || bytes(name_).length == 0) revert JBERC20_AlreadyInitialized();
-
+    function setMetadata(string memory name_, string memory symbol_) external override onlyTokens {
         _name = name_;
         _symbol = symbol_;
-
-        // Transfer ownership to the owner.
-        _transferOwnership(owner);
     }
 
     //*********************************************************************//
-    // ------------------------- external views -------------------------- //
+    // ----------------------- external views ---------------------------- //
     //*********************************************************************//
 
     /// @notice This token can only be added to a project when its created by the `JBTokens` contract.
@@ -99,6 +123,35 @@ contract JBERC20 is ERC20Votes, ERC20Permit, Ownable, IJBToken {
         return false;
     }
 
+    /// @notice Validates a signature on behalf of this token contract (ERC-1271).
+    /// @dev Allows the project owner or an operator with `SIGN_FOR_ERC20` permission to sign messages on behalf of
+    /// this token. Useful for Etherscan contract verification and other off-chain signature flows.
+    /// @param hash The hash of the data being signed.
+    /// @param signature The signature to validate.
+    /// @return magicValue `0x1626ba7e` if the signature is valid, `0xffffffff` otherwise.
+    function isValidSignature(bytes32 hash, bytes memory signature) external view override returns (bytes4 magicValue) {
+        // Recover the signer from the signature. Return invalid if recovery fails.
+        // slither-disable-next-line unused-return
+        (address signer, ECDSA.RecoverError error,) = ECDSA.tryRecover(hash, signature);
+        if (error != ECDSA.RecoverError.NoError) return 0xffffffff;
+
+        // Get the project ID this token belongs to.
+        uint256 projectId = TOKENS.projectIdOf(IJBToken(address(this)));
+
+        // Get the project owner (the NFT holder).
+        address projectOwner = PROJECTS.ownerOf(projectId);
+
+        // Valid if the signer is the project owner or has the SIGN_FOR_ERC20 permission.
+        if (_hasPermissionFrom({
+                operator: signer,
+                account: projectOwner,
+                projectId: projectId,
+                permissionId: JBPermissionIds.SIGN_FOR_ERC20
+            })) return IERC1271.isValidSignature.selector;
+
+        return 0xffffffff;
+    }
+
     //*********************************************************************//
     // -------------------------- public views --------------------------- //
     //*********************************************************************//
@@ -137,6 +190,23 @@ contract JBERC20 is ERC20Votes, ERC20Permit, Ownable, IJBToken {
         return super.totalSupply();
     }
 
+    //*********************************************************************//
+    // ----------------------- public transactions ----------------------- //
+    //*********************************************************************//
+
+    /// @notice Initializes the token.
+    /// @param name_ The token's name.
+    /// @param symbol_ The token's symbol.
+    /// @param tokens The JBTokens contract that manages this token.
+    function initialize(string memory name_, string memory symbol_, address tokens) public override {
+        // Prevent re-initialization by reverting if a name is already set or if the provided name is empty.
+        if (bytes(_name).length != 0 || bytes(name_).length == 0) revert JBERC20_AlreadyInitialized();
+
+        _name = name_;
+        _symbol = symbol_;
+        TOKENS = IJBTokens(tokens);
+    }
+
     //*********************************************************************//
     // ---------------------- internal transactions ---------------------- //
     //*********************************************************************//

package/src/JBTerminalStore.sol

@@ -599,6 +599,8 @@ contract JBTerminalStore is IJBTerminalStore {
         JBRuleset memory ruleset = RULESETS.currentOf(projectId);
 
         // Return the amount of surplus terminal tokens that would be reclaimed.
+        // NOTE: This view does not run the data hook, so it cannot reflect a cross-chain totalSupply override.
+        // For accurate omnichain estimates, use the data hook or simulate recordCashOutFor.
         return JBCashOuts.cashOutFrom({
             surplus: surplus,
             cashOutCount: cashOutCount,
@@ -814,6 +816,8 @@ contract JBTerminalStore is IJBTerminalStore {
         if (cashOutCount > totalSupply) return 0;
 
         // Return the amount of surplus terminal tokens that would be reclaimed.
+        // NOTE: This view does not run the data hook, so it cannot reflect a cross-chain totalSupply override.
+        // For accurate omnichain estimates, use the data hook or simulate recordCashOutFor.
         return JBCashOuts.cashOutFrom({
             surplus: currentSurplus,
             cashOutCount: cashOutCount,
@@ -877,6 +881,54 @@ contract JBTerminalStore is IJBTerminalStore {
         });
     }
 
+    /// @notice Calls the data hook, validates noop specifications, and computes the bonding curve reclaim amount.
+    /// @dev Extracted from `_computeCashOutFrom` to keep it under the EVM stack depth limit (16 slots).
+    /// @param ruleset The current ruleset (used to resolve the data hook address).
+    /// @param context The fully-populated cash out context to forward to the data hook.
+    /// @param surplus The locally available surplus (used as a cap — can't reclaim more than what's on-chain here).
+    /// @return reclaimAmount The amount of surplus tokens reclaimable after the bonding curve and cap.
+    /// @return cashOutTaxRate The cash out tax rate returned by the data hook.
+    /// @return hookSpecifications The hook specifications returned by the data hook.
+    function _cashOutWithDataHook(
+        JBRuleset memory ruleset,
+        JBBeforeCashOutRecordedContext memory context,
+        uint256 surplus
+    )
+        internal
+        view
+        returns (uint256 reclaimAmount, uint256 cashOutTaxRate, JBCashOutHookSpecification[] memory hookSpecifications)
+    {
+        // Ask the data hook for the effective bonding curve parameters and any hook specifications.
+        uint256 effectiveCashOutCount;
+        uint256 effectiveTotalSupply;
+        uint256 effectiveSurplusValue;
+        (cashOutTaxRate, effectiveCashOutCount, effectiveTotalSupply, effectiveSurplusValue, hookSpecifications) =
+            IJBRulesetDataHook(ruleset.dataHook()).beforeCashOutRecordedWith(context);
+
+        // Noop specifications are informational only, so they can't also request forwarded funds.
+        for (uint256 i; i < hookSpecifications.length;) {
+            if (hookSpecifications[i].noop && hookSpecifications[i].amount != 0) {
+                revert JBTerminalStore_NoopHookSpecHasAmount(hookSpecifications[i].amount);
+            }
+            unchecked {
+                ++i;
+            }
+        }
+
+        // Apply the bonding curve to calculate how much of the surplus is reclaimable.
+        if (surplus != 0) {
+            reclaimAmount = JBCashOuts.cashOutFrom({
+                surplus: effectiveSurplusValue,
+                cashOutCount: effectiveCashOutCount,
+                totalSupply: effectiveTotalSupply,
+                cashOutTaxRate: cashOutTaxRate
+            });
+
+            // Cap at local surplus — can't reclaim more than what's locally available.
+            if (reclaimAmount > surplus) reclaimAmount = surplus;
+        }
+    }
+
     /// @notice Computes cash out results without writing state.
     /// @param terminal The terminal recording the cash out.
     /// @param holder The account that is cashing out tokens.
@@ -934,8 +986,6 @@ contract JBTerminalStore is IJBTerminalStore {
         // The terminal still burns the caller-supplied cashOutCount after pricing completes.
         // Project owners MUST audit their data hooks with the same rigor as the terminal.
 
-        uint256 effectiveCashOutCount = cashOutCount;
-
         // If the ruleset has a data hook which is enabled for cash outs, use it to derive a claim amount and memo.
         if (ruleset.useDataHookForCashOut() && ruleset.dataHook() != address(0)) {
             // Build the cash out context field-by-field — the struct has 11 fields, too many for a literal.
@@ -957,30 +1007,21 @@ contract JBTerminalStore is IJBTerminalStore {
             context.beneficiaryIsFeeless = beneficiaryIsFeeless;
             context.metadata = metadata;
 
-            (cashOutTaxRate, effectiveCashOutCount, effectiveTotalSupply, hookSpecifications) =
-                IJBRulesetDataHook(ruleset.dataHook()).beforeCashOutRecordedWith(context);
-
-            // Noop specifications are informational only, so they can't also request forwarded funds.
-            for (uint256 i; i < hookSpecifications.length;) {
-                if (hookSpecifications[i].noop && hookSpecifications[i].amount != 0) {
-                    revert JBTerminalStore_NoopHookSpecHasAmount(hookSpecifications[i].amount);
-                }
-                unchecked {
-                    ++i;
-                }
-            }
+            // Hook call + bonding curve in a helper to stay under the stack depth limit.
+            (reclaimAmount, cashOutTaxRate, hookSpecifications) =
+                _cashOutWithDataHook({ruleset: ruleset, context: context, surplus: surplus});
         } else {
             cashOutTaxRate = ruleset.cashOutTaxRate();
-        }
 
-        // Apply the bonding curve to calculate how much of the surplus is reclaimable.
-        if (surplus != 0) {
-            reclaimAmount = JBCashOuts.cashOutFrom({
-                surplus: surplus,
-                cashOutCount: effectiveCashOutCount,
-                totalSupply: effectiveTotalSupply,
-                cashOutTaxRate: cashOutTaxRate
-            });
+            // Apply the bonding curve to calculate how much of the surplus is reclaimable.
+            if (surplus != 0) {
+                reclaimAmount = JBCashOuts.cashOutFrom({
+                    surplus: surplus,
+                    cashOutCount: cashOutCount,
+                    totalSupply: effectiveTotalSupply,
+                    cashOutTaxRate: cashOutTaxRate
+                });
+            }
         }
     }
 

package/src/JBTokens.sol

@@ -228,7 +228,7 @@ contract JBTokens is JBControlled, IJBTokens {
         });
 
         // Initialize the token.
-        token.initialize({name: name, symbol: symbol, owner: address(this)});
+        token.initialize({name: name, symbol: symbol, tokens: address(this)});
     }
 
     /// @notice Mint (create) new tokens or credits.