@bananapus/core-v6 0.0.17 → 0.0.19

package/CHANGE_LOG.md

@@ -10,6 +10,23 @@ This document describes all changes between `nana-core` (v5, Solidity 0.8.23) an
 
 `setSplitGroupsOf` self-auth now requires the upper 96 bits of the `groupId` to be non-zero. The full self-auth check is: `uint160(groupId) == msg.sender && groupId >> 160 != 0`. GroupIds with zero upper 96 bits (bare addresses like `uint256(uint160(tokenAddress))`) are protocol-reserved for terminal payout groups and always require controller authorization. This prevents accepted token contracts from writing a project's payout splits without controller auth. The 721 hook is unaffected since it already uses `hookAddress | tierId << 160` (non-zero upper bits).
 
+### 0.2 JBMultiTerminal -- Fee-Free Cashout Bypass Prevention
+
+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.
+
 ---
 
 ## 1. Breaking Changes
@@ -29,16 +46,19 @@ A `rulesetId` parameter was added. Callers must now specify which ruleset to cac
 | Change | v5 | v6 |
 |--------|----|----|
 | `currentReclaimableSurplusOf` parameter rename | `uint256 tokenCount` (4-param overload) | `uint256 cashOutCount` |
+| `recordCashOutFor` new parameter | No `beneficiaryIsFeeless` parameter | `bool beneficiaryIsFeeless` added after `balanceAccountingContexts` |
 
 The parameter was renamed from `tokenCount` to `cashOutCount` in the simple 4-parameter overload.
 
+`recordCashOutFor` gained a `bool beneficiaryIsFeeless` parameter so the terminal can pass through its feeless address check to data hooks via the `JBBeforeCashOutRecordedContext` struct.
+
 #### IJBPayoutTerminal
 
 | Change | v5 | v6 |
 |--------|----|----|
 | `sendPayoutsOf` return value | `returns (uint256 netLeftoverPayoutAmount)` | `returns (uint256 amountPaidOut)` |
 
-The return value semantics changed: v5 returned the net leftover payout amount (sent to the project owner), while v6 returns the total amount paid out.
+The return variable name was corrected from `netLeftoverPayoutAmount` to `amountPaidOut` to match the actual implementation semantics (total amount paid out). The v5 implementation already returned the total amount from `STORE.recordPayoutFor()`, not the leftover — only the interface had the misleading name.
 
 #### IJBController
 
@@ -80,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 |
@@ -141,8 +167,8 @@ See section 2.2 above.
 
 | Contract | Event | Change |
 |----------|-------|--------|
-| `IJBCashOutTerminal` | `CashOut` | Event order changed in the interface (moved before `HookAfterRecordCashOut`); NatSpec added. No field changes. |
-| `IJBCashOutTerminal` | `HookAfterRecordCashOut` | Event order changed in the interface (moved after `CashOut`); NatSpec added. No field changes. |
+| `IJBCashOutTerminal` | `CashOutTokens` | Event order changed in the interface (moved before `HookAfterRecordCashOut`); NatSpec added. No field changes. |
+| `IJBCashOutTerminal` | `HookAfterRecordCashOut` | Event order changed in the interface (moved after `CashOutTokens`); NatSpec added. No field changes. |
 
 ### 3.3 All Interfaces Gained NatSpec
 
@@ -189,7 +215,13 @@ See section 2.3 above.
 
 ## 5. Struct Changes
 
-All structs are **identical** between v5 and v6. The only differences are:
+All structs are identical between v5 and v6 except:
+
+| Struct | Change |
+|--------|--------|
+| `JBBeforeCashOutRecordedContext` | New `bool beneficiaryIsFeeless` field added before `metadata`. Indicates whether the cash out's beneficiary is a feeless address, allowing data hooks to skip their own fees for in-protocol routing. |
+
+Other struct-level differences (non-functional):
 - `forge-lint: disable-next-line(pascal-case-struct)` comments added to all struct definitions.
 - `JBSplit`: Additional NatSpec documentation on the `beneficiary` field behavior when set to `address(0)`.
 
@@ -269,6 +301,8 @@ No changes.
 | **Migration held fees** | Migration intentionally does not transfer held fees (documented: held fees belong to fee beneficiary, not the migrating project). |
 | **Held fee processing (reentrancy hardening)** | `processHeldFeesOf` now re-reads the storage index each iteration (instead of caching), deletes the entry before the external call, and updates the index before the external call. |
 | **Split payout documentation** | Failed split payouts documented as consuming payout limit by design. |
+| **Fee-free cashout bypass prevention** | New `_feeFreeSurplusOf` mapping tracks cumulative fee-free intra-terminal payouts per project/token. During zero-tax cashouts, fees are charged up to this tracked amount (then decremented), preventing round-trip fee bypass. See Section 0.2. |
+| **beneficiaryIsFeeless passthrough** | `cashOutTokensOf` now passes `_isFeeless(beneficiary)` to `recordCashOutFor`, which forwards it to data hooks via `JBBeforeCashOutRecordedContext.beneficiaryIsFeeless`. |
 
 ### 8.3 JBRulesets
 
@@ -285,36 +319,42 @@ No changes.
 |--------|-------------|
 | **Migration ordering** | `setControllerOf` now calls `migrate()` on the old controller BEFORE updating `controllerOf` in storage (so `migrate()` runs while the directory still points to the old controller). After updating storage, it calls `afterReceiveMigrationFrom` on the new controller. |
 
-### 8.5 JBTokens
+### 8.5 JBSplits
+
+| Change | Description |
+|--------|-------------|
+| **Stale storage cleanup** | `_setSplitsOf` now deletes stale packed split data when the new split count is smaller than the previous count, preventing leftover storage from prior configurations. |
+
+### 8.6 JBTokens
 
 | Change | Description |
 |--------|-------------|
 | **Overflow check timing** | `mintFor` now checks `totalSupplyOf(projectId) + count > type(uint208).max` BEFORE minting (v5 checked after). |
 
-### 8.6 JBERC20
+### 8.7 JBERC20
 
 | Change | Description |
 |--------|-------------|
 | **Named revert** | `initialize()` now reverts with `JBERC20_AlreadyInitialized()` instead of a bare `revert()`. |
 
-### 8.7 JBChainlinkV3PriceFeed
+### 8.8 JBChainlinkV3PriceFeed
 
 | Change | Description |
 |--------|-------------|
 | **Incomplete round check order** | The check for `updatedAt == 0` (incomplete round) now runs BEFORE the stale price check, avoiding false stale errors on incomplete rounds. |
 
-### 8.8 JBChainlinkV3SequencerPriceFeed
+### 8.9 JBChainlinkV3SequencerPriceFeed
 
 | Change | Description |
 |--------|-------------|
 | **Typo fix** | Error parameter `gradePeriodTime` corrected to `gracePeriodTime` in `JBChainlinkV3SequencerPriceFeed_SequencerDown`. |
 | **Threshold docs** | Constructor parameter `threshold` documentation corrected from "blocks" to "seconds". |
 
-### 8.9 Solidity Version
+### 8.10 Solidity Version
 
 All contracts upgraded from `pragma solidity 0.8.23` to `pragma solidity 0.8.26`.
 
-### 8.10 Named Arguments
+### 8.11 Named Arguments
 
 Throughout the codebase, function calls were updated to use named argument syntax (e.g., `foo({bar: 1, baz: 2})`) for improved readability.
 
@@ -328,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`. 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 |
@@ -344,7 +384,7 @@ Throughout the codebase, function calls were updated to use named argument synta
 | v5 | v6 | Notes |
 |----|----|-------|
 | `JBController` | `JBController` | Token metadata, migration lifecycle (`afterReceiveMigrationFrom`), `LAUNCH_RULESETS` permission |
-| `JBMultiTerminal` | `JBMultiTerminal` | Reentrancy hardening, decimal validation rename, Permit2 event |
+| `JBMultiTerminal` | `JBMultiTerminal` | Reentrancy hardening, decimal validation rename, Permit2 event, fee-free bypass prevention (`_feeFreeSurplusOf`), `beneficiaryIsFeeless` passthrough |
 | `JBRulesets` | `JBRulesets` | Approval hook try/catch, weight cache changes, threshold increase |
 | `JBDirectory` | `JBDirectory` | Migration ordering fix, afterReceiveMigration call |
 | `JBTokens` | `JBTokens` | Token metadata support, overflow check timing |
@@ -366,7 +406,7 @@ Throughout the codebase, function calls were updated to use named argument synta
 
 | v5 | v6 | Notes |
 |----|----|-------|
-| All 22 structs | Same names, same fields | Only lint comments added |
+| All 22 structs | Same names | All identical except `JBBeforeCashOutRecordedContext` (gained `beneficiaryIsFeeless` field). Lint comments added to all. |
 
 ### Enums
 

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.17",
+  "version": "0.0.19",
   "license": "MIT",
   "repository": {
     "type": "git",