@bananapus/core-v6 0.0.18 → 0.0.19

package/CHANGE_LOG.md

@@ -14,6 +14,15 @@ This document describes all changes between `nana-core` (v5, Solidity 0.8.23) an
 
 A new `_feeFreeSurplusOf` mapping (`projectId => token => uint256`) tracks cumulative fee-free intra-terminal payouts received by each project. When a split payout lands on the same terminal (intra-terminal routing, i.e. `terminal == this`), the net payout amount is added to `_feeFreeSurplusOf[projectId][token]`. During a cashout with `cashOutTaxRate == 0`, fees are now charged on the reclaim amount up to the tracked fee-free surplus (and the tracker is decremented accordingly). Cashouts beyond the fee-free surplus remain fee-free. This closes a round-trip fee bypass where funds could be routed fee-free into a project via an intra-terminal split payout and then cashed out fee-free via a zero-tax cashout.
 
+### 0.4 JBTerminalStore -- Preview Functions
+
+Two new `view` functions added to `JBTerminalStore` and `IJBTerminalStore`:
+
+- `previewPayFrom(address terminal, address payer, JBTokenAmount amount, uint256 projectId, address beneficiary, bytes metadata)` -- Simulates a payment and returns `(uint256 tokenCount, JBPayHookSpecification[] hookSpecifications)`. Invokes data hooks if configured. Does not modify state.
+- `previewCashOutFrom(address terminal, address holder, uint256 projectId, uint256 cashOutCount, JBAccountingContext accountingContext, JBAccountingContext[] balanceAccountingContexts, bool beneficiaryIsFeeless, bytes metadata)` -- Simulates a cash out and returns `(uint256 reclaimAmount, uint256 cashOutTaxRate, JBCashOutHookSpecification[] hookSpecifications)`. Invokes data hooks if configured. Does not modify state.
+
+Both functions use the explicit `terminal` parameter instead of `msg.sender`, allowing any caller to preview operations for any terminal. Internal computation logic was extracted into shared `_computePayFrom` and `_computeCashOutFrom` view helpers; the existing `recordPaymentFrom` and `recordCashOutFor` functions were refactored to call these helpers before writing state.
+
 ### 0.3 JBBeforeCashOutRecordedContext -- beneficiaryIsFeeless Field
 
 A `bool beneficiaryIsFeeless` field was added to the `JBBeforeCashOutRecordedContext` struct (before the `metadata` field). `recordCashOutFor` in `IJBTerminalStore` gained a corresponding `bool beneficiaryIsFeeless` parameter. The terminal passes the result of its feeless address check, allowing data hooks to skip their own fees when the beneficiary is already feeless (e.g., project-to-project routing via the router terminal). This is a **breaking change** to both the struct layout and the `recordCashOutFor` function signature.
@@ -91,6 +100,12 @@ Parameters changed from `memory` to `calldata` for gas efficiency.
 | `setTokenMetadataOf(uint256 projectId, string name, string symbol)` | Sets the name and symbol of a project's ERC-20 token. Requires the `SET_TOKEN_METADATA` permission. |
 | `afterReceiveMigrationFrom(IERC165 from, uint256 projectId)` | Called by the directory after this controller has been set as the active controller. Added to the `IJBMigratable` interface. |
 
+#### IJBTerminalStore / JBTerminalStore
+
+| Function | Description |
+|----------|-------------|
+| `currentTotalReclaimableSurplusOf(uint256 projectId, uint256 cashOutCount, uint256 decimals, uint256 currency)` | Convenience view that returns the reclaimable surplus across all terminals using all accounting contexts. Delegates to `currentReclaimableSurplusOf` with empty `terminals` and `accountingContexts` arrays. Mirrors the `currentTotalSurplusOf` pattern. |
+
 #### IJBTokens / JBTokens
 
 | Function | Description |
@@ -353,7 +368,7 @@ Throughout the codebase, function calls were updated to use named argument synta
 |----|----|-------|
 | `IJBController` | `IJBController` | Gained `setTokenMetadataOf`. `calldata` for terminal configs. |
 | `IJBRulesets` | `IJBRulesets` | `updateRulesetWeightCache` gained `rulesetId` parameter |
-| `IJBTerminalStore` | `IJBTerminalStore` | `tokenCount` renamed to `cashOutCount` in `currentReclaimableSurplusOf`. `recordCashOutFor` gained `beneficiaryIsFeeless` param. View functions reordered. |
+| `IJBTerminalStore` | `IJBTerminalStore` | `tokenCount` renamed to `cashOutCount` in `currentReclaimableSurplusOf`. `recordCashOutFor` gained `beneficiaryIsFeeless` param. New `currentTotalReclaimableSurplusOf` convenience view. View functions reordered. |
 | `IJBPayoutTerminal` | `IJBPayoutTerminal` | `sendPayoutsOf` returns `amountPaidOut` (was `netLeftoverPayoutAmount`). `SendPayoutToSplit` event moved. |
 | `IJBPermitTerminal` | `IJBPermitTerminal` | Gained `Permit2AllowanceFailed` event |
 | `IJBMigratable` | `IJBMigratable` | Gained `afterReceiveMigrationFrom` function |

package/SKILLS.md

@@ -83,7 +83,13 @@ The core Juicebox V6 protocol on EVM: a modular system for launching treasury-ba
 | `balanceOf(address terminal, uint256 projectId, address token)` | Returns the balance of a project at a terminal for a given token. |
 | `usedPayoutLimitOf(address terminal, uint256 projectId, address token, uint256 rulesetCycleNumber, uint256 currency)` | Returns the used payout limit for a project in a given cycle. |
 | `usedSurplusAllowanceOf(address terminal, uint256 projectId, address token, uint256 rulesetId, uint256 currency)` | Returns the used surplus allowance for a project in a given ruleset. |
+| `currentReclaimableSurplusOf(uint256 projectId, uint256 cashOutCount, uint256 totalSupply, uint256 surplus)` | Returns the reclaimable surplus given raw total supply and surplus values. Applies bonding curve from current ruleset. |
+| `currentReclaimableSurplusOf(uint256 projectId, uint256 cashOutCount, IJBTerminal[] terminals, JBAccountingContext[] accountingContexts, uint256 decimals, uint256 currency)` | Returns the reclaimable surplus across specified terminals. Empty arrays default to all terminals/contexts. |
+| `currentTotalReclaimableSurplusOf(uint256 projectId, uint256 cashOutCount, uint256 decimals, uint256 currency)` | Convenience view: reclaimable surplus across all terminals using all accounting contexts. Mirrors `currentTotalSurplusOf`. |
 | `currentSurplusOf(address terminal, uint256 projectId, JBAccountingContext[] accountingContexts, uint256 decimals, uint256 currency)` | Returns the current surplus for a project at a terminal. |
+| `currentTotalSurplusOf(uint256 projectId, uint256 decimals, uint256 currency)` | Returns the total surplus across all terminals. |
+| `previewPayFrom(address terminal, address payer, JBTokenAmount amount, uint256 projectId, address beneficiary, bytes metadata)` | Simulates a payment without modifying state. Invokes data hooks if configured. Returns token count and hook specifications. |
+| `previewCashOutFrom(address terminal, address holder, uint256 projectId, uint256 cashOutCount, JBAccountingContext accountingContext, JBAccountingContext[] balanceAccountingContexts, bool beneficiaryIsFeeless, bytes metadata)` | Simulates a cash out without modifying state. Invokes data hooks if configured. Returns reclaim amount, tax rate, and hook specifications. |
 
 ### JBRulesets
 

package/USER_JOURNEYS.md

@@ -69,6 +69,8 @@ All user paths through the Juicebox V6 core protocol. For each journey: entry po
 - Data hook can return empty weight (0) to suppress minting while still recording payment
 - Fee-on-transfer tokens: actual amount received is `_balanceOf(token) - balanceBefore` (measured via balance diff)
 
+**Preview**: Call `JBTerminalStore.previewPayFrom(terminal, payer, amount, projectId, beneficiary, metadata)` to simulate the payment on-chain and see the exact token count and hook specifications that would be produced -- including data hook effects. This is a `view` function that does not modify state.
+
 ---
 
 ## 3. Cash Out Tokens
@@ -95,6 +97,8 @@ All user paths through the Juicebox V6 core protocol. For each journey: entry po
 
 **Events**: `CashOutTokens(rulesetId, rulesetCycleNumber, projectId, holder, beneficiary, cashOutCount, cashOutTaxRate, reclaimAmount, metadata, caller)`
 
+**Preview**: Call `JBTerminalStore.previewCashOutFrom(terminal, holder, projectId, cashOutCount, accountingContext, balanceAccountingContexts, beneficiaryIsFeeless, metadata)` to simulate the full cash out on-chain -- including data hook effects on tax rate, supply, and hook specifications. This is a `view` function that does not modify state. For a simpler estimate without data hook effects, use `currentTotalReclaimableSurplusOf(projectId, cashOutCount, decimals, currency)` or the 6-param `currentReclaimableSurplusOf` overload.
+
 **Edge cases**:
 - `cashOutCount = 0` with `totalSupply = 0` -- returns entire surplus (C-5 known bug)
 - `cashOutTaxRate = MAX (10,000)` -- returns 0 (all surplus locked)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/core-v6",
-  "version": "0.0.18",
+  "version": "0.0.19",
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/JBTerminalStore.sol

@@ -184,99 +184,25 @@ contract JBTerminalStore is IJBTerminalStore {
             JBCashOutHookSpecification[] memory hookSpecifications
         )
     {
-        // Get a reference to the project's current ruleset.
-        ruleset = RULESETS.currentOf(projectId);
-
-        // Store the current surplus in `reclaimAmount` temporarily to avoid allocating a separate local variable
-        // (saves one stack slot, which is needed to fit the 7th parameter without hitting stack-too-deep).
-        reclaimAmount = ruleset.useTotalSurplusForCashOuts()
-            ? JBSurplus.currentSurplusOf({
-                projectId: projectId,
-                terminals: DIRECTORY.terminalsOf(projectId),
-                accountingContexts: new JBAccountingContext[](0),
-                decimals: accountingContext.decimals,
-                currency: accountingContext.currency
-            })
-            : _surplusFrom({
-                terminal: msg.sender,
-                projectId: projectId,
-                accountingContexts: balanceAccountingContexts,
-                ruleset: ruleset,
-                targetDecimals: accountingContext.decimals,
-                targetCurrency: accountingContext.currency
-            });
-
-        // Scoped to keep `totalSupply` and `context` off the outer stack.
-        {
-            // Get the total number of outstanding project tokens.
-            uint256 totalSupply = IJBController(address(DIRECTORY.controllerOf(projectId)))
-                .totalTokenSupplyWithReservedTokensOf(projectId);
-
-            // Can't cash out more tokens than are in the supply.
-            if (cashOutCount > totalSupply) revert JBTerminalStore_InsufficientTokens(cashOutCount, totalSupply);
-
-            // SECURITY NOTE: The data hook has absolute control over cash-out economics.
-            // It can set totalSupply, cashOutCount, and cashOutTaxRate to arbitrary values,
-            // completely overriding the terminal's bonding curve math. For example, setting
-            // totalSupply = surplus makes reclaimAmount = cashOutCount, bypassing the curve.
-            // Project owners MUST audit their data hooks with the same rigor as the terminal.
-
-            // 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 to avoid stack-too-deep
-                // (the struct has 11 fields — a struct literal would require all values on the stack at once).
-                JBBeforeCashOutRecordedContext memory context;
-                context.terminal = msg.sender;
-                context.holder = holder;
-                context.projectId = projectId;
-                context.rulesetId = ruleset.id;
-                context.cashOutCount = cashOutCount;
-                context.totalSupply = totalSupply;
-                context.surplus = JBTokenAmount({
-                    token: accountingContext.token,
-                    value: reclaimAmount, // reclaimAmount temporarily holds the current surplus.
-                    decimals: accountingContext.decimals,
-                    currency: accountingContext.currency
-                });
-                context.useTotalSurplus = ruleset.useTotalSurplusForCashOuts();
-                context.cashOutTaxRate = ruleset.cashOutTaxRate();
-                context.beneficiaryIsFeeless = beneficiaryIsFeeless;
-                context.metadata = metadata;
-
-                (cashOutTaxRate, cashOutCount, totalSupply, hookSpecifications) =
-                    IJBRulesetDataHook(ruleset.dataHook()).beforeCashOutRecordedWith(context);
-            } else {
-                cashOutTaxRate = ruleset.cashOutTaxRate();
-            }
-
-            // Calculate the reclaim amount. `reclaimAmount` currently holds the surplus — overwrite it with the
-            // result.
-            if (reclaimAmount != 0) {
-                reclaimAmount = JBCashOuts.cashOutFrom({
-                    surplus: reclaimAmount,
-                    cashOutCount: cashOutCount,
-                    totalSupply: totalSupply,
-                    cashOutTaxRate: cashOutTaxRate
-                });
-            }
-        }
+        (ruleset, reclaimAmount, cashOutTaxRate, hookSpecifications) = _computeCashOutFrom({
+            terminal: msg.sender,
+            holder: holder,
+            projectId: projectId,
+            cashOutCount: cashOutCount,
+            accountingContext: accountingContext,
+            balanceAccountingContexts: balanceAccountingContexts,
+            beneficiaryIsFeeless: beneficiaryIsFeeless,
+            metadata: metadata
+        });
 
-        // Keep a reference to the amount that should be added to the project's balance.
+        // Compute the total amount to subtract from the project's balance.
         uint256 balanceDiff = reclaimAmount;
 
-        // Ensure that the specifications have valid amounts.
         if (hookSpecifications.length != 0) {
-            // Keep a reference to the number of cash out hooks specified.
             uint256 numberOfSpecifications = hookSpecifications.length;
-
-            // Loop through each specification.
             for (uint256 i; i < numberOfSpecifications; i++) {
-                // Get a reference to the specification's amount.
                 uint256 specificationAmount = hookSpecifications[i].amount;
-
-                // Ensure the amount is non-zero.
                 if (specificationAmount != 0) {
-                    // Increment the total amount being subtracted from the balance.
                     balanceDiff += specificationAmount;
                 }
             }
@@ -323,98 +249,21 @@ contract JBTerminalStore is IJBTerminalStore {
         override
         returns (JBRuleset memory ruleset, uint256 tokenCount, JBPayHookSpecification[] memory hookSpecifications)
     {
-        // Get a reference to the project's current ruleset.
-        ruleset = RULESETS.currentOf(projectId);
-
-        // The project must have a ruleset.
-        if (ruleset.cycleNumber == 0) revert JBTerminalStore_RulesetNotFound(projectId);
-
-        // The ruleset must not have payments paused.
-        if (ruleset.pausePay()) revert JBTerminalStore_RulesetPaymentPaused();
-
-        // The weight according to which new tokens are to be minted, as a fixed point number with 18 decimals.
-        uint256 weight;
-
-        // SECURITY NOTE: The data hook has absolute control over payment token minting.
-        // It can return an arbitrary weight (overriding the ruleset's weight) and hook specifications
-        // that divert payment funds to external hooks before they reach the project's balance.
-        // Project owners MUST audit their data hooks with the same rigor as the terminal.
-
-        // If the ruleset has a data hook enabled for payments, use it to derive a weight and memo.
-        if (ruleset.useDataHookForPay() && ruleset.dataHook() != address(0)) {
-            // Create the pay context that'll be sent to the data hook.
-            JBBeforePayRecordedContext memory context = JBBeforePayRecordedContext({
-                terminal: msg.sender,
-                payer: payer,
-                amount: amount,
-                projectId: projectId,
-                rulesetId: ruleset.id,
-                beneficiary: beneficiary,
-                weight: ruleset.weight,
-                reservedPercent: ruleset.reservedPercent(),
-                metadata: metadata
-            });
-
-            (weight, hookSpecifications) = IJBRulesetDataHook(ruleset.dataHook()).beforePayRecordedWith(context);
-        }
-        // Otherwise use the ruleset's weight
-        else {
-            weight = ruleset.weight;
-        }
-
-        // Keep a reference to the amount that should be added to the project's balance.
-        uint256 balanceDiff = amount.value;
-
-        // Scoped section preventing stack too deep.
-        {
-            // Keep a reference to the number of hook specifications.
-            uint256 numberOfSpecifications = hookSpecifications.length;
-
-            // Ensure that the specifications have valid amounts.
-            for (uint256 i; i < numberOfSpecifications; i++) {
-                // Get a reference to the specification's amount.
-                uint256 specifiedAmount = hookSpecifications[i].amount;
-
-                // Ensure the amount is non-zero.
-                if (specifiedAmount != 0) {
-                    // Can't send more to hook than was paid.
-                    if (specifiedAmount > balanceDiff) {
-                        revert JBTerminalStore_InvalidAmountToForwardHook(specifiedAmount, balanceDiff);
-                    }
-
-                    // Decrement the total amount being added to the local balance.
-                    balanceDiff -= specifiedAmount;
-                }
-            }
-        }
-
-        // If there's no amount being recorded, there's nothing left to do.
-        if (amount.value == 0) return (ruleset, 0, hookSpecifications);
+        uint256 balanceDiff;
+        (ruleset, tokenCount, hookSpecifications, balanceDiff) = _computePayFrom({
+            terminal: msg.sender,
+            payer: payer,
+            amount: amount,
+            projectId: projectId,
+            beneficiary: beneficiary,
+            metadata: metadata
+        });
 
         // Add the correct balance difference to the token balance of the project.
         if (balanceDiff != 0) {
             balanceOf[msg.sender][projectId][amount.token] =
                 balanceOf[msg.sender][projectId][amount.token] + balanceDiff;
         }
-
-        // If there's no weight, the token count must be 0, so there's nothing left to do.
-        if (weight == 0) return (ruleset, 0, hookSpecifications);
-
-        // If the terminal should base its weight on a currency other than the terminal's currency, determine the
-        // factor. The weight is always a fixed point mumber with 18 decimals. To ensure this, the ratio should use the
-        // same
-        // number of decimals as the `amount`.
-        uint256 weightRatio = amount.currency == ruleset.baseCurrency()
-            ? 10 ** amount.decimals
-            : PRICES.pricePerUnitOf({
-                projectId: projectId,
-                pricingCurrency: amount.currency,
-                unitCurrency: ruleset.baseCurrency(),
-                decimals: amount.decimals
-            });
-
-        // Find the number of tokens to mint, as a fixed point number with as many decimals as `weight` has.
-        tokenCount = mulDiv(amount.value, weight, weightRatio);
     }
 
     /// @notice Records a payout from a project.
@@ -699,6 +548,34 @@ contract JBTerminalStore is IJBTerminalStore {
         });
     }
 
+    /// @notice Returns the number of surplus terminal tokens that would be reclaimed by cashing out a given number of
+    /// tokens across all of a project's terminals using all accounting contexts.
+    /// @param projectId The ID of the project whose tokens would be cashed out.
+    /// @param cashOutCount The number of tokens that would be cashed out, as a fixed point number with 18 decimals.
+    /// @param decimals The number of decimals to include in the resulting fixed point number.
+    /// @param currency The currency that the resulting number will be in terms of.
+    /// @return The amount of surplus terminal tokens that would be reclaimed by cashing out `cashOutCount` tokens.
+    function currentTotalReclaimableSurplusOf(
+        uint256 projectId,
+        uint256 cashOutCount,
+        uint256 decimals,
+        uint256 currency
+    )
+        external
+        view
+        override
+        returns (uint256)
+    {
+        return this.currentReclaimableSurplusOf({
+            projectId: projectId,
+            cashOutCount: cashOutCount,
+            terminals: new IJBTerminal[](0),
+            accountingContexts: new JBAccountingContext[](0),
+            decimals: decimals,
+            currency: currency
+        });
+    }
+
     /// @notice Gets the current surplus amount in a terminal for a specified project.
     /// @dev The surplus is the amount of funds a project has in a terminal in excess of its payout limit.
     /// @dev The surplus is represented as a fixed point number with the same amount of decimals as the specified
@@ -757,10 +634,319 @@ contract JBTerminalStore is IJBTerminalStore {
         });
     }
 
+    /// @notice Simulates a cash out without modifying state.
+    /// @dev Invokes data hooks if configured, but skips the balance sufficiency check (balance may change between
+    /// preview and execution).
+    /// @param terminal The terminal address to simulate the cash out from.
+    /// @param holder The address cashing out.
+    /// @param projectId The ID of the project being cashed out from.
+    /// @param cashOutCount The number of project tokens being cashed out.
+    /// @param accountingContext The accounting context of the token being reclaimed.
+    /// @param balanceAccountingContexts The accounting contexts to include in the balance calculation.
+    /// @param beneficiaryIsFeeless Whether the cash out's beneficiary is a feeless address.
+    /// @param metadata Extra data to pass along to the data hook.
+    /// @return ruleset The project's current ruleset.
+    /// @return reclaimAmount The amount that would be reclaimed.
+    /// @return cashOutTaxRate The cash out tax rate that would be applied.
+    /// @return hookSpecifications Any cash out hook specifications from the data hook.
+    function previewCashOutFrom(
+        address terminal,
+        address holder,
+        uint256 projectId,
+        uint256 cashOutCount,
+        JBAccountingContext calldata accountingContext,
+        JBAccountingContext[] calldata balanceAccountingContexts,
+        bool beneficiaryIsFeeless,
+        bytes calldata metadata
+    )
+        external
+        view
+        override
+        returns (
+            JBRuleset memory ruleset,
+            uint256 reclaimAmount,
+            uint256 cashOutTaxRate,
+            JBCashOutHookSpecification[] memory hookSpecifications
+        )
+    {
+        (ruleset, reclaimAmount, cashOutTaxRate, hookSpecifications) = _computeCashOutFrom({
+            terminal: terminal,
+            holder: holder,
+            projectId: projectId,
+            cashOutCount: cashOutCount,
+            accountingContext: accountingContext,
+            balanceAccountingContexts: balanceAccountingContexts,
+            beneficiaryIsFeeless: beneficiaryIsFeeless,
+            metadata: metadata
+        });
+    }
+
+    /// @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.
+    /// @param terminal The terminal address to simulate the payment from.
+    /// @param payer The address of the payer.
+    /// @param amount The amount being paid.
+    /// @param projectId The ID of the project being paid.
+    /// @param beneficiary The address to mint project tokens to.
+    /// @param metadata Extra data to pass along to the data hook.
+    /// @return ruleset The project's current ruleset.
+    /// @return tokenCount The number of project tokens that would be minted.
+    /// @return hookSpecifications Any pay hook specifications from the data hook.
+    function previewPayFrom(
+        address terminal,
+        address payer,
+        JBTokenAmount memory amount,
+        uint256 projectId,
+        address beneficiary,
+        bytes calldata metadata
+    )
+        external
+        view
+        override
+        returns (JBRuleset memory ruleset, uint256 tokenCount, JBPayHookSpecification[] memory hookSpecifications)
+    {
+        (ruleset, tokenCount, hookSpecifications,) = _computePayFrom({
+            terminal: terminal,
+            payer: payer,
+            amount: amount,
+            projectId: projectId,
+            beneficiary: beneficiary,
+            metadata: metadata
+        });
+    }
+
     //*********************************************************************//
     // -------------------------- internal views ------------------------- //
     //*********************************************************************//
 
+    /// @notice Computes payment results without writing state.
+    /// @param terminal The terminal recording the payment.
+    /// @param payer The address that made the payment.
+    /// @param amount The amount of tokens being paid.
+    /// @param projectId The ID of the project being paid.
+    /// @param beneficiary The beneficiary of the payment.
+    /// @param metadata Bytes to send to the data hook.
+    /// @return ruleset The ruleset the payment would be made during.
+    /// @return tokenCount The number of project tokens that would be minted.
+    /// @return hookSpecifications Pay hook specifications from the data hook.
+    /// @return balanceDiff The amount that would be added to the project's balance.
+    function _computePayFrom(
+        address terminal,
+        address payer,
+        JBTokenAmount memory amount,
+        uint256 projectId,
+        address beneficiary,
+        bytes memory metadata
+    )
+        internal
+        view
+        returns (
+            JBRuleset memory ruleset,
+            uint256 tokenCount,
+            JBPayHookSpecification[] memory hookSpecifications,
+            uint256 balanceDiff
+        )
+    {
+        // Get a reference to the project's current ruleset.
+        ruleset = RULESETS.currentOf(projectId);
+
+        // The project must have a ruleset.
+        if (ruleset.cycleNumber == 0) revert JBTerminalStore_RulesetNotFound(projectId);
+
+        // The ruleset must not have payments paused.
+        if (ruleset.pausePay()) revert JBTerminalStore_RulesetPaymentPaused();
+
+        // The weight according to which new tokens are to be minted, as a fixed point number with 18 decimals.
+        uint256 weight;
+
+        // SECURITY NOTE: The data hook has absolute control over payment token minting.
+        // It can return an arbitrary weight (overriding the ruleset's weight) and hook specifications
+        // that divert payment funds to external hooks before they reach the project's balance.
+        // Project owners MUST audit their data hooks with the same rigor as the terminal.
+
+        // If the ruleset has a data hook enabled for payments, use it to derive a weight and memo.
+        if (ruleset.useDataHookForPay() && ruleset.dataHook() != address(0)) {
+            // Create the pay context that'll be sent to the data hook.
+            JBBeforePayRecordedContext memory context = JBBeforePayRecordedContext({
+                terminal: terminal,
+                payer: payer,
+                amount: amount,
+                projectId: projectId,
+                rulesetId: ruleset.id,
+                beneficiary: beneficiary,
+                weight: ruleset.weight,
+                reservedPercent: ruleset.reservedPercent(),
+                metadata: metadata
+            });
+
+            (weight, hookSpecifications) = IJBRulesetDataHook(ruleset.dataHook()).beforePayRecordedWith(context);
+        }
+        // Otherwise use the ruleset's weight
+        else {
+            weight = ruleset.weight;
+        }
+
+        // Keep a reference to the amount that should be added to the project's balance.
+        balanceDiff = amount.value;
+
+        // Scoped section preventing stack too deep.
+        {
+            // Keep a reference to the number of hook specifications.
+            uint256 numberOfSpecifications = hookSpecifications.length;
+
+            // Ensure that the specifications have valid amounts.
+            for (uint256 i; i < numberOfSpecifications; i++) {
+                // Get a reference to the specification's amount.
+                uint256 specifiedAmount = hookSpecifications[i].amount;
+
+                // Ensure the amount is non-zero.
+                if (specifiedAmount != 0) {
+                    // Can't send more to hook than was paid.
+                    if (specifiedAmount > balanceDiff) {
+                        revert JBTerminalStore_InvalidAmountToForwardHook(specifiedAmount, balanceDiff);
+                    }
+
+                    // Decrement the total amount being added to the local balance.
+                    balanceDiff -= specifiedAmount;
+                }
+            }
+        }
+
+        // If there's no amount being recorded, there's nothing left to do.
+        if (amount.value == 0) return (ruleset, 0, hookSpecifications, 0);
+
+        // If there's no weight, the token count must be 0, so there's nothing left to do.
+        if (weight == 0) return (ruleset, 0, hookSpecifications, balanceDiff);
+
+        // If the terminal should base its weight on a currency other than the terminal's currency, determine the
+        // factor. The weight is always a fixed point mumber with 18 decimals. To ensure this, the ratio should use the
+        // same
+        // number of decimals as the `amount`.
+        uint256 weightRatio = amount.currency == ruleset.baseCurrency()
+            ? 10 ** amount.decimals
+            : PRICES.pricePerUnitOf({
+                projectId: projectId,
+                pricingCurrency: amount.currency,
+                unitCurrency: ruleset.baseCurrency(),
+                decimals: amount.decimals
+            });
+
+        // Find the number of tokens to mint, as a fixed point number with as many decimals as `weight` has.
+        tokenCount = mulDiv(amount.value, weight, weightRatio);
+    }
+
+    /// @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.
+    /// @param projectId The ID of the project being cashed out from.
+    /// @param cashOutCount The number of project tokens to cash out.
+    /// @param accountingContext The accounting context of the token being reclaimed.
+    /// @param balanceAccountingContexts The accounting contexts of the tokens whose balances should contribute to the
+    /// surplus being reclaimed from.
+    /// @param beneficiaryIsFeeless Whether the cash out's beneficiary is a feeless address.
+    /// @param metadata Bytes to send to the data hook.
+    /// @return ruleset The ruleset during the cash out.
+    /// @return reclaimAmount The amount of tokens reclaimed.
+    /// @return cashOutTaxRate The cash out tax rate applied.
+    /// @return hookSpecifications Cash out hook specifications from the data hook.
+    function _computeCashOutFrom(
+        address terminal,
+        address holder,
+        uint256 projectId,
+        uint256 cashOutCount,
+        JBAccountingContext calldata accountingContext,
+        JBAccountingContext[] calldata balanceAccountingContexts,
+        bool beneficiaryIsFeeless,
+        bytes memory metadata
+    )
+        internal
+        view
+        returns (
+            JBRuleset memory ruleset,
+            uint256 reclaimAmount,
+            uint256 cashOutTaxRate,
+            JBCashOutHookSpecification[] memory hookSpecifications
+        )
+    {
+        // Get a reference to the project's current ruleset.
+        ruleset = RULESETS.currentOf(projectId);
+
+        // Store the current surplus in `reclaimAmount` temporarily to avoid allocating a separate local variable
+        // (saves one stack slot, which is needed to fit the 7th parameter without hitting stack-too-deep).
+        reclaimAmount = ruleset.useTotalSurplusForCashOuts()
+            ? JBSurplus.currentSurplusOf({
+                projectId: projectId,
+                terminals: DIRECTORY.terminalsOf(projectId),
+                accountingContexts: new JBAccountingContext[](0),
+                decimals: accountingContext.decimals,
+                currency: accountingContext.currency
+            })
+            : _surplusFrom({
+                terminal: terminal,
+                projectId: projectId,
+                accountingContexts: balanceAccountingContexts,
+                ruleset: ruleset,
+                targetDecimals: accountingContext.decimals,
+                targetCurrency: accountingContext.currency
+            });
+
+        // Scoped to keep `totalSupply` and `context` off the outer stack.
+        {
+            // Get the total number of outstanding project tokens.
+            uint256 totalSupply = IJBController(address(DIRECTORY.controllerOf(projectId)))
+                .totalTokenSupplyWithReservedTokensOf(projectId);
+
+            // Can't cash out more tokens than are in the supply.
+            if (cashOutCount > totalSupply) revert JBTerminalStore_InsufficientTokens(cashOutCount, totalSupply);
+
+            // SECURITY NOTE: The data hook has absolute control over cash-out economics.
+            // It can set totalSupply, cashOutCount, and cashOutTaxRate to arbitrary values,
+            // completely overriding the terminal's bonding curve math. For example, setting
+            // totalSupply = surplus makes reclaimAmount = cashOutCount, bypassing the curve.
+            // Project owners MUST audit their data hooks with the same rigor as the terminal.
+
+            // 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 to avoid stack-too-deep
+                // (the struct has 11 fields — a struct literal would require all values on the stack at once).
+                JBBeforeCashOutRecordedContext memory context;
+                context.terminal = terminal;
+                context.holder = holder;
+                context.projectId = projectId;
+                context.rulesetId = ruleset.id;
+                context.cashOutCount = cashOutCount;
+                context.totalSupply = totalSupply;
+                context.surplus = JBTokenAmount({
+                    token: accountingContext.token,
+                    value: reclaimAmount, // reclaimAmount temporarily holds the current surplus.
+                    decimals: accountingContext.decimals,
+                    currency: accountingContext.currency
+                });
+                context.useTotalSurplus = ruleset.useTotalSurplusForCashOuts();
+                context.cashOutTaxRate = ruleset.cashOutTaxRate();
+                context.beneficiaryIsFeeless = beneficiaryIsFeeless;
+                context.metadata = metadata;
+
+                (cashOutTaxRate, cashOutCount, totalSupply, hookSpecifications) =
+                    IJBRulesetDataHook(ruleset.dataHook()).beforeCashOutRecordedWith(context);
+            } else {
+                cashOutTaxRate = ruleset.cashOutTaxRate();
+            }
+
+            // Calculate the reclaim amount. `reclaimAmount` currently holds the surplus — overwrite it with the
+            // result.
+            if (reclaimAmount != 0) {
+                reclaimAmount = JBCashOuts.cashOutFrom({
+                    surplus: reclaimAmount,
+                    cashOutCount: cashOutCount,
+                    totalSupply: totalSupply,
+                    cashOutTaxRate: cashOutTaxRate
+                });
+            }
+        }
+    }
+
     /// @notice Gets a project's surplus amount in a terminal as measured by a given ruleset, across multiple accounting
     /// contexts.
     /// @dev This amount changes as the value of the balance changes in relation to the currency being used to measure