@bananapus/core-v6 0.0.24 → 0.0.25

package/ADMINISTRATION.md

@@ -97,7 +97,7 @@ Admin privileges and their scope in nana-core-v6.
 
 | Function | Required Role | Permission ID | Scope | What It Does |
 |----------|--------------|---------------|-------|-------------|
-| `addPriceFeed` | Project owner or operator | ADD_PRICE_FEED (19) | Per project | Adds a price feed for a project. Requires the ruleset's `allowAddPriceFeed` flag. Price feeds are immutable once set. |
+| `addPriceFeedFor` | Project owner or operator | ADD_PRICE_FEED (19) | Per project | Adds a price feed for a project. Requires the ruleset's `allowAddPriceFeed` flag. Price feeds are immutable once set. |
 | `burnTokensOf` | Token holder, operator with BURN_TOKENS, or a project terminal | BURN_TOKENS (11) | Per project | Burns tokens or credits from a holder's balance. Terminals can burn without explicit permission (for cash outs). |
 | `claimTokensFor` | Credit holder or operator | CLAIM_TOKENS (12) | Per project | Redeems internal credits for ERC-20 tokens. |
 | `deployERC20For` | Project owner or operator | DEPLOY_ERC20 (8) | Per project | Deploys a new ERC-20 token contract for the project. Can only be called once per project. |
@@ -200,6 +200,19 @@ JBTerminalStore has no explicit access control modifiers. Instead, it uses `msg.
 | `recordTerminalMigration` | Any address (terminal) | Records a full balance migration. Requires the ruleset's `allowTerminalMigration` flag. Zeros out the caller's balance. |
 | `recordUsedAllowanceOf` | Any address (terminal) | Records surplus allowance usage. Decrements the caller's balance. |
 
+## Deployment Dependencies
+
+Contracts must be deployed in dependency order. The constructor dependency graph:
+
+1. **No dependencies:** JBPermissions, JBProjects, JBERC20 (implementation), JBFeelessAddresses
+2. **Depends on (1):** JBDirectory (← JBPermissions, JBProjects)
+3. **Depends on (2):** JBRulesets, JBSplits, JBFundAccessLimits, JBTokens (← JBDirectory); JBPrices (← JBDirectory, JBPermissions, JBProjects)
+4. **Depends on (3):** JBTerminalStore (← JBDirectory, JBPrices, JBRulesets)
+5. **Depends on (1-4):** JBController (← JBDirectory, JBFundAccessLimits, JBPermissions, JBPrices, JBProjects, JBRulesets, JBSplits, JBTokens + omnichainRulesetOperator address)
+6. **Depends on (1-4):** JBMultiTerminal (← JBTerminalStore, JBFeelessAddresses, JBPermissions, JBProjects, JBSplits, JBTokens, Permit2)
+
+After deployment, `JBDirectory.setIsAllowedToSetFirstController()` must be called to authorize the controller. The first project (ID 1, the fee project) is created automatically in the `JBProjects` constructor.
+
 ## Permission System
 
 JBPermissions implements a 256-bit packed permission bitmap system:
@@ -232,7 +245,7 @@ JBPermissions implements a 256-bit packed permission bitmap system:
 | 16 | SET_PRIMARY_TERMINAL | `JBDirectory.setPrimaryTerminalOf` |
 | 17 | USE_ALLOWANCE | `JBMultiTerminal.useAllowanceOf` |
 | 18 | SET_SPLIT_GROUPS | `JBController.setSplitGroupsOf` |
-| 19 | ADD_PRICE_FEED | `JBController.addPriceFeed` |
+| 19 | ADD_PRICE_FEED | `JBController.addPriceFeedFor` |
 | 20 | ADD_ACCOUNTING_CONTEXTS | `JBMultiTerminal.addAccountingContextsFor` |
 | 21 | SET_TOKEN_METADATA | `JBController.setTokenMetadataOf` |
 
@@ -308,7 +321,7 @@ Several admin functions are further gated by boolean flags in the active ruleset
 | `allowSetTerminals` | Whether `setTerminalsOf` can be called by non-controller callers. |
 | `allowSetController` | Whether `setControllerOf` can be called (checked via `IJBDirectoryAccessControl`). |
 | `allowAddAccountingContext` | Whether `addAccountingContextsFor` can add new token contexts. |
-| `allowAddPriceFeed` | Whether `addPriceFeed` can add new price feeds. |
+| `allowAddPriceFeed` | Whether `addPriceFeedFor` can add new price feeds. |
 | `ownerMustSendPayouts` | Whether `sendPayoutsOf` requires SEND_PAYOUTS permission (otherwise anyone can call it). |
 | `pausePay` | Whether payments are paused (checked in JBTerminalStore). |
 | `pauseCreditTransfers` | Whether credit transfers are paused. |

package/ARCHITECTURE.md

@@ -27,14 +27,27 @@ src/
 ├── abstract/
 │   ├── JBPermissioned.sol — Base for permission-checked contracts
 │   └── JBControlled.sol   — Base for controller-gated contracts
+├── enums/
+│   └── JBApprovalStatus.sol       — Approval hook status enum
+├── periphery/
+│   ├── JBDeadline1Day.sol         — 1-day approval hook
+│   ├── JBDeadline3Days.sol        — 3-day approval hook
+│   ├── JBDeadline3Hours.sol       — 3-hour approval hook
+│   ├── JBDeadline7Days.sol        — 7-day approval hook
+│   └── JBMatchingPriceFeed.sol    — 1:1 price feed
+├── interfaces/                    — 30 interface files (IJBController, IJBTerminal, etc.)
+├── structs/                       — 22 struct files (JBRuleset, JBSplit, etc.)
 └── libraries/
     ├── JBCashOuts.sol              — Bonding curve math
+    ├── JBConstants.sol             — Protocol constants
+    ├── JBCurrencyIds.sol           — Currency ID constants (ETH, USD)
     ├── JBFees.sol                  — Fee calculation (forward/backward)
-    ├── JBRulesetMetadataResolver.sol — Bit-packed metadata (256 bits)
-    ├── JBMetadataResolver.sol      — Variable-length key-value metadata
     ├── JBFixedPointNumber.sol      — Decimal adjustment
-    ├── JBConstants.sol             — Protocol constants
-    └── JBSplitGroupIds.sol         — Split group ID constants
+    ├── JBMetadataResolver.sol      — Variable-length key-value metadata
+    ├── JBPayoutSplitGroupLib.sol   — Payout split group helpers
+    ├── JBRulesetMetadataResolver.sol — Bit-packed metadata (256 bits)
+    ├── JBSplitGroupIds.sol         — Split group ID constants
+    └── JBSurplus.sol               — Cross-terminal surplus calculation
 ```
 
 ## Key Data Flows
@@ -66,10 +79,16 @@ Holder -> JBMultiTerminal.cashOutTokensOf()
     -> JBCashOuts.cashOutFrom() — bonding curve
     -> Deduct balance
   -> JBController.burnTokensOf()
-  -> Transfer reclaimed tokens to beneficiary
+  -> Deduct fee from reclaim amount (if applicable), transfer remainder to beneficiary
   -> [Optional] Cash out hooks execute
-  -> Take fees (2.5% to project #1) if cashOutTaxRate > 0
-     OR if cashOutTaxRate == 0 and project has unconsumed fee-free surplus (_feeFreeSurplusOf)
+  -> Send accumulated fees to project #1
+     Fees apply when cashOutTaxRate > 0 (on full reclaim)
+     OR when cashOutTaxRate == 0 and project has unconsumed _feeFreeSurplusOf (on that portion only)
+     _feeFreeSurplusOf lifecycle:
+       - Incremented on fee-free intra-terminal payouts
+       - Capped at remaining balance after any outflow (payouts, useAllowanceOf, non-zero-tax/feeless cashouts) — non-fee-free funds leave first
+       - Consumed (decremented by feeable amount) during zero-tax cashouts
+       - Cleared to zero on terminal migration (migrateBalanceOf)
 ```
 
 ### Preview Flow
@@ -117,7 +136,7 @@ Owner -> JBMultiTerminal.sendPayoutsOf()
 | Data Hook (cashout) | `IJBRulesetDataHook.beforeCashOutRecordedWith` | JBTerminalStore |
 | Pay Hook | `IJBPayHook.afterPayRecordedWith` | JBMultiTerminal |
 | Cash Out Hook | `IJBCashOutHook.afterCashOutRecordedWith` | JBMultiTerminal |
-| Split Hook | `IJBSplitHook.processSplitWith` | JBMultiTerminal |
+| Split Hook | `IJBSplitHook.processSplitWith` | JBMultiTerminal, JBController |
 | Approval Hook | `IJBRulesetApprovalHook.approvalStatusOf` | JBRulesets |
 
 ## Dependencies
@@ -130,7 +149,7 @@ Owner -> JBMultiTerminal.sendPayoutsOf()
 
 ## Key Constants
 
-- FEE = 25 (2.5%), MAX_FEE = 1000
+- FEE = 25 (2.5%) — defined on JBMultiTerminal, MAX_FEE = 1000 — defined in JBConstants
 - MAX_RESERVED_PERCENT = 10,000 (basis points)
 - MAX_CASH_OUT_TAX_RATE = 10,000
 - MAX_WEIGHT_CUT_PERCENT = 1,000,000,000 (9 decimals)

package/AUDIT_INSTRUCTIONS.md

@@ -6,7 +6,7 @@ Read [RISKS.md](./RISKS.md) for known risks, trust model, and reentrancy analysi
 
 ## Architecture Overview
 
-16 contracts, ~6,300 lines in main contracts. All contracts use Solidity 0.8.26.
+16 contracts, ~8,100 lines in main contracts. All contracts use Solidity 0.8.28.
 
 ```
                               JBProjects (ERC-721)
@@ -27,21 +27,21 @@ Read [RISKS.md](./RISKS.md) for known risks, trust model, and reentrancy analysi
 | Contract | Lines | Role | Calls |
 |----------|-------|------|-------|
 | **JBMultiTerminal** | ~2024 | Payment terminal. Handles pay, cash out, payouts, surplus allowance, fees, and previews (`previewPayFor`, `previewCashOutFrom`). Multi-token. Permit2 integration. | Store, Controller, Splits, Directory, Prices |
-| **JBController** | ~1186 | Orchestrator. Project lifecycle, ruleset queuing, token minting/burning, reserved token distribution, mint preview (`previewMintOf`). ERC-2771 meta-tx. | Rulesets, Tokens, Splits, FundAccessLimits, Directory, Prices |
-| **JBTerminalStore** | ~800 | Bookkeeping. Balances, payout limit tracking, surplus calculation, bonding curve reclaim math. Data hook integration point. | Rulesets, Prices, Directory |
+| **JBController** | ~1,253 | Orchestrator. Project lifecycle, ruleset queuing, token minting/burning, reserved token distribution, mint preview (`previewMintOf`). ERC-2771 meta-tx. | Rulesets, Tokens, Splits, FundAccessLimits, Directory, Prices |
+| **JBTerminalStore** | ~1,267 | Bookkeeping. Balances, payout limit tracking, surplus calculation, bonding curve reclaim math. Data hook integration point. | Rulesets, Prices, Directory |
 | **JBRulesets** | ~1093 | Ruleset lifecycle. Linked-list via `basedOnId`. Weight decay with cache (20k iteration threshold). Approval hooks. Bit-packed storage. | Directory (via JBControlled) |
-| **JBDirectory** | ~300 | Routes projects to terminals and controllers. Migration lifecycle (before/after). | Projects, Permissions |
-| **JBTokens** | ~300 | Dual token system: credits (internal) + ERC-20. Credits burned first on burn. 18-decimal requirement. | JBERC20 (clone) |
-| **JBSplits** | ~300 | Packed split storage per project/ruleset/group. Locked splits enforcement. Fallback to ruleset 0. | -- |
-| **JBFundAccessLimits** | ~200 | Payout limits and surplus allowances per terminal/token/currency. Strictly increasing currency order. | -- |
-| **JBPrices** | ~200 | Price feed registry. Project-specific + default fallback. Immutable once set. Inverse auto-calculation. | Chainlink feeds |
+| **JBDirectory** | ~344 | Routes projects to terminals and controllers. Migration lifecycle (before/after). | Projects, Permissions |
+| **JBTokens** | ~415 | Dual token system: credits (internal) + ERC-20. Credits burned first on burn. 18-decimal requirement. | JBERC20 (clone) |
+| **JBSplits** | ~333 | Packed split storage per project/ruleset/group. Locked splits enforcement. Fallback to ruleset 0. | -- |
+| **JBFundAccessLimits** | ~318 | Payout limits and surplus allowances per terminal/token/currency. Strictly increasing currency order. | -- |
+| **JBPrices** | ~233 | Price feed registry. Project-specific + default fallback. Immutable once set. Inverse auto-calculation. | Chainlink feeds |
 | **JBPermissions** | ~260 | 256-bit packed permission bitmap. ROOT (1) grants all. Wildcard projectId=0. ERC-2771. | -- |
-| **JBProjects** | ~100 | ERC-721 project ownership. Auto-incrementing IDs. | -- |
-| **JBERC20** | ~200 | Cloneable ERC20Votes+Permit. Owned by JBTokens. Deployed via `Clones.clone()`. | -- |
+| **JBProjects** | ~126 | ERC-721 project ownership. Auto-incrementing IDs. | -- |
+| **JBERC20** | ~144 | Cloneable ERC20Votes+Permit. Owned by JBTokens. Deployed via `Clones.clone()`. | -- |
 | **JBFeelessAddresses** | ~50 | Fee-exempt address registry. Owner-only. | -- |
-| **JBDeadline** | ~100 | Approval hook. Rejects rulesets queued within DURATION seconds of start. Ships as 3h, 1d, 3d, 7d variants. | -- |
-| **JBChainlinkV3PriceFeed** | ~80 | Chainlink v3 feed with staleness threshold. Rejects negative/zero/incomplete. | Chainlink AggregatorV3 |
-| **JBChainlinkV3SequencerPriceFeed** | ~120 | L2 sequencer-aware Chainlink feed. Grace period after restart. | Chainlink AggregatorV3 + Sequencer feed |
+| **JBDeadline** | ~76 | Approval hook. Rejects rulesets queued within DURATION seconds of start. Ships as 3h, 1d, 3d, 7d variants. | -- |
+| **JBChainlinkV3PriceFeed** | ~74 | Chainlink v3 feed with staleness threshold. Rejects negative/zero/incomplete. | Chainlink AggregatorV3 |
+| **JBChainlinkV3SequencerPriceFeed** | ~75 | L2 sequencer-aware Chainlink feed. Grace period after restart. | Chainlink AggregatorV3 + Sequencer feed |
 
 ## Key Flows
 
@@ -88,7 +88,7 @@ Holder -> JBMultiTerminal.cashOutTokensOf()
      -> Fee skipped if beneficiary is feeless
 ```
 
-**Critical note**: The beneficiary receives the reclaim amount BEFORE cash out hooks execute. Fees are taken AFTER hooks. `_feeFreeSurplusOf[projectId][token]` accumulates the value of fee-free intra-terminal payouts. During zero-tax cashout, the 2.5% fee applies only up to this surplus amount (then depletes it), preventing a round-trip fee bypass (payout via same terminal → zero-tax cashout) while scoping fees precisely to the fee-free inflow.
+**Critical note**: The beneficiary receives the reclaim amount BEFORE cash out hooks execute. Fees are taken AFTER hooks. `_feeFreeSurplusOf[projectId][token]` accumulates the value of fee-free intra-terminal 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. During zero-tax cashout, the 2.5% fee applies only up to this surplus amount (then depletes it), preventing a round-trip fee bypass. Cleared on terminal migration.
 
 ### Payout Flow (`sendPayoutsOf`)
 
@@ -99,7 +99,7 @@ Anyone -> JBMultiTerminal.sendPayoutsOf()
      -> Deduct amount from balance
      -> Increment usedPayoutLimitOf
      -> Validate against FUND_ACCESS_LIMITS.payoutLimitOf()
-  -> _sendPayoutsToSplitGroupOf()
+  -> JBPayoutSplitGroupLib.sendPayoutsToSplitGroupOf()
      -> Get splits from JBSplits.splitsOf()
      -> For each split (try-catch per split):
         -> Split to hook: deduct fee, call hook.processSplitWith() with funds
@@ -258,7 +258,7 @@ These are the patterns that will trip you up if you are not aware of them:
 8. **`sendPayoutsOf()` reverts when `amount > payout limit`** -- does NOT auto-cap to limit.
 9. **Cash out tax rate semantics are inverted from what you might expect**: 0% = proportional (1:1) redemption. 100% = nothing reclaimable (all surplus locked).
 10. **`recordPayoutFor` deducts balance and increments used limit BEFORE validation** -- safe because the entire transaction reverts atomically, but the ordering matters for reentrancy analysis.
-11. **Try-catch on external calls** -- `_sendPayoutToSplit`, `_processFee`, `executePayReservedTokenToTerminal` all use try-catch. Failed calls return funds to project balance and emit events. This is NOT a bug -- it prevents single-point-of-failure DoS.
+11. **Try-catch on external calls** -- `JBPayoutSplitGroupLib._sendPayoutToSplit`, `_processFee`, `executePayReservedTokenToTerminal` all use try-catch. Failed calls return funds to project balance and emit events. This is NOT a bug -- it prevents single-point-of-failure DoS.
 12. **Credits are burned before ERC-20 tokens** in `JBTokens.burnFrom()`.
 13. **`JBERC20` is cloned via `Clones.clone()`** -- constructor sets invalid name/symbol; real values set in `initialize()`.
 14. **Named returns auto-return** -- several functions use named return variables without explicit `return` statements.
@@ -301,7 +301,7 @@ forge test --match-contract Invariant
 forge test --gas-report
 ```
 
-The existing test suite has 165 test files including:
+The existing test suite has 185 test files including:
 - **Integration tests**: Full flow tests for pay, cash out, payouts
 - **Formal property tests**: 7 bonding curve properties + 6 fee properties
 - **Invariant tests**: TerminalStore (5), Phase3Deep (8), Rulesets (4), Tokens (4)
@@ -341,4 +341,89 @@ For each finding:
 - **MEDIUM**: Value leakage, griefing with cost to attacker, incorrect accounting, degraded functionality.
 - **LOW**: Informational, cosmetic inconsistency, edge-case-only with no material impact.
 
+## Attack Vectors
+
+These are the attack patterns most likely to yield findings in core. Ordered by estimated likelihood of undiscovered bugs.
+
+### 1. Hook Composition Attacks
+
+Hooks execute after state is partially committed. Data hooks control weight and fund allocation absolutely. Pay/cashout hooks receive diverted funds and can re-enter the protocol.
+
+**Specific sequences to test:**
+- Data hook returns `totalSupply = surplus` during `beforeCashOutRecordedWith` → `reclaimAmount = cashOutCount`, completely bypassing the bonding curve. Verify all constraints on hook return values.
+- Data hook sets `weight = type(uint256).max` during pay → can this overflow in `mulDiv(amount.value, weight, weightRatio)`?
+- Pay hook calls `cashOutTokensOf` on the same project during `afterPayRecordedWith`. Tokens are minted and store is updated. Is the cashout profitable given the inflated balance?
+- Split hook calls `pay()` on the same project during `sendPayoutsOf`. Payout limit is consumed but new payment adds to balance and mints tokens. Does this create a value loop?
+- Cash out hook calls `pay()` on same project. Tokens are burned before hooks execute, but new tokens are minted. Can this inflate supply?
+
+### 2. Bonding Curve Economic Attacks
+
+The cash out formula: `reclaimAmount = (surplus * count / supply) * [(MAX - tax) + tax * (count / supply)] / MAX`
+
+**Sequences:**
+- Pay → immediate cash out in same block: should never profit after fees. Test with different hook configurations.
+- Pay with data hook that inflates weight → cash out before reserved tokens are distributed. Pending reserved tokens inflate `totalSupply` (H-4 finding).
+- Cash out with `cashOutCount >= totalSupply` returns entire surplus (C-5 finding, by design). Can you engineer this condition without being the last holder? (e.g., front-running a burn)
+- Cross-terminal surplus aggregation: `useTotalSurplusForCashOuts` aggregates surplus across all terminals via `JBSurplus`. Can you manipulate surplus in one terminal to inflate cashout value in another?
+
+### 3. Reentrancy Through CEI Ordering
+
+No contract uses `ReentrancyGuard`. The protocol relies on checks-effects-interactions ordering.
+
+**Critical surfaces (in order of risk):**
+1. **Pay hook → cash out**: After `recordPaymentFrom` + `mintTokensOf`, the hook executes. It could call `cashOutTokensOf`. Store balance and tokens are updated. Is the resulting cashout computed against post-payment state correctly?
+2. **Split hook → pay**: During `sendPayoutsOf`, splits receive funds. A hook could call `pay()`. Payout limit is consumed, but new payment updates state.
+3. **Fee processing → re-entry**: `_processFee` calls `terminal.pay()` on project #1's terminal. If project #1 has a pay hook that calls back into the originating terminal, the fee is already deducted.
+4. **processHeldFeesOf**: Re-reads storage index each iteration, updates index BEFORE external call. Verify this ordering prevents re-entrancy exploitation.
+
+### 4. Ruleset Transition Timing
+
+Rulesets transition at exact block timestamps. Transaction ordering at boundaries matters.
+
+**What to test:**
+- Payment at last second of ruleset vs. first second of next: both should execute with correct weights.
+- Approval hook rejection at boundary: fallback to `basedOnId` chain simulates cycling from last approved ruleset. Is this always equivalent?
+- `duration = 0` rulesets immediately replaced when new one queued. Can you pay and queue in the same tx to get old weight but new parameters?
+- Weight decay across 20,000+ cycles without cache: `WeightCacheRequired` revert = DoS. Can an attacker force a project into this state?
+
+## Anti-Patterns to Hunt
+
+| Pattern | Where to Look | Why It's Dangerous |
+|---------|--------------|-------------------|
+| `try-catch` swallowing errors | JBMultiTerminal (hooks, fees, splits) | Failed external calls silently change control flow. Fee try-catch enables temporary fee avoidance. |
+| `mulDiv` rounding direction | JBCashOuts, JBFees, JBTerminalStore | Rounding in attacker's favor compounds over many transactions. Verify rounding favors the protocol. |
+| Currency type confusion | JBTerminalStore, JBFundAccessLimits | Abstract (1=ETH, 2=USD) vs concrete (`uint32(address)`) currencies. `groupId` (`uint256`) vs `currency` (`uint32`) truncation. |
+| Named returns without explicit `return` | JBTerminalStore, JBRulesets | Auto-return of named variables. Easy to miss intermediate assignments that change the return value. |
+| Bit-packed metadata shifts | JBRulesetMetadataResolver | Off-by-one in shift amounts or mask widths corrupts adjacent fields. 256-bit layout with 17 fields. |
+| State before validation | `recordPayoutFor` | Balance deducted and limit incremented BEFORE validation. Safe due to atomic revert, but matters for reentrancy analysis. |
+| Lazy evaluation of pending state | `pendingReservedTokenBalanceOf` | Reserved tokens accumulate but aren't minted until `sendReservedTokensToSplitsOf`. `totalSupply` includes pending. |
+| External call in loop | Payout splits, `processHeldFeesOf` | Gas griefing via reverting external calls. Each caught by try-catch but still costs gas. |
+
+## Previous Audit Findings
+
+| ID | Severity | Status | Description |
+|----|----------|--------|-------------|
+| C-5 | Critical | Known/Accepted | `cashOut(0)` with `totalSupply == 0` returns entire surplus. By design — last holder gets everything. Documented in `FlashLoanAttacks.t.sol`. |
+| H-4 | High | Known/Accepted | Pending reserved tokens inflate `totalSupply` in bonding curve calculation, reducing cashout value by 50%+ in extreme cases. Distributing reserved tokens via `sendReservedTokensToSplitsOf` before cashing out mitigates. |
+| FV-1 | Low | Known/Accepted | Bonding curve subadditivity violation from `mulDiv` rounding. Measured at <0.01%, economically insignificant. Proven bounded in formal property tests. |
+
+## Coverage Gaps
+
+The 185 test files cover most flows, but these areas have limited or no coverage:
+
+- **Multi-hook composition**: No end-to-end tests for data hook + pay hook + cashout hook interacting in a single flow with reentrancy.
+- **Extreme weight decay**: Weight decay beyond 20,000 cycles tested for revert, but not for precision loss at exactly the cache threshold boundary.
+- **Cross-terminal surplus manipulation**: No tests where surplus is manipulated in terminal A to inflate cashout value in terminal B via `useTotalSurplusForCashOuts`.
+- **Approval hook edge cases**: Limited testing of approval hook state changes between `queueRulesetsOf` and ruleset start time.
+- **Concurrent held fee processing**: `processHeldFeesOf` tested sequentially but not under reentrancy from fee payment hooks.
+- **ERC-2771 meta-tx spoofing**: No tests verifying that a malicious forwarder cannot spoof `_msgSender()` to bypass permissions.
+
+## Compiler and Version Info
+
+- **Solidity**: 0.8.28
+- **EVM target**: Cancun (uses transient storage opcodes)
+- **Optimizer**: 200 runs (no via-IR)
+- **Dependencies**: OpenZeppelin 5.x, Solady, forge-std
+- **Build**: `forge build` (Foundry)
+
 Go break it.

package/CHANGE_LOG.md

@@ -1,6 +1,14 @@
 # nana-core-v6 Changelog (v5 -> v6)
 
-This document describes all changes between `nana-core` (v5, Solidity 0.8.23) and `nana-core-v6` (v6, Solidity 0.8.26).
+This document describes all changes between `nana-core` (v5, Solidity 0.8.23) and `nana-core-v6` (v6, Solidity 0.8.28).
+
+## Summary
+
+- **Preview APIs**: New `previewPayFor` and `previewCashOutFrom` view functions on terminal and store for simulating payments/cashouts without state changes.
+- **Fee-free cashout bypass closed**: Intra-terminal payouts now tracked via `_feeFreeSurplusOf` to prevent round-trip fee evasion through zero-tax cashouts.
+- **Approval hook hardening**: Reverting approval hooks now return `Failed` status instead of propagating, preventing permanent project freezing.
+- **Weight cache overhaul**: Cache threshold raised from 1,000 to 20,000 iterations; exceeding the threshold now reverts instead of silently iterating.
+- **Token metadata now mutable**: New `setTokenMetadataOf` allows changing a project token's name and symbol post-deployment.
 
 ---
 
@@ -12,7 +20,11 @@ This document describes all changes between `nana-core` (v5, Solidity 0.8.23) an
 
 ### 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.
+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]`. After any outflow (payouts via `sendPayoutsOf`, surplus allowance via `useAllowanceOf`, non-zero-tax or feeless cashouts), the counter is capped at the remaining balance — non-fee-free funds are considered to leave first, preserving the fee-free counter as long as possible. During a cashout with `cashOutTaxRate == 0`, fees are 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. The counter is cleared on terminal migration. 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.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.
 
 ### 0.4 JBTerminalStore -- Preview Functions
 
@@ -36,10 +48,6 @@ Also in this release:
 - **`via_ir = true`**: Added to `foundry.toml` to enable the Solidity IR optimizer pipeline, reducing deployed bytecode size (EIP-170 compliance).
 - Internal helpers extracted: `_accountingContextOf` and `_tokenAmountOf` on `JBMultiTerminal`, `_splitTokenCount` on `JBController`.
 
-### 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
@@ -81,6 +89,7 @@ The return variable name was corrected from `netLeftoverPayoutAmount` to `amount
 | `launchRulesetsFor` terminal configs | `JBTerminalConfig[] memory terminalConfigurations` | `JBTerminalConfig[] calldata terminalConfigurations` |
 
 Parameters changed from `memory` to `calldata` for gas efficiency.
+> **Cross-repo impact**: The `calldata` change affects `nana-omnichain-deployers-v6` and `revnet-core-v6`, which call `launchProjectFor`/`launchRulesetsFor`.
 
 #### IJBSplits
 
@@ -167,6 +176,7 @@ Parameters changed from `memory` to `calldata` for gas efficiency.
 |------------|-------------|
 | `LAUNCH_RULESETS` | Required for `launchRulesetsFor`. In v5, `QUEUE_RULESETS` was used. |
 | `SET_TOKEN_METADATA` | Required for `setTokenMetadataOf`. |
+> **Cross-repo impact**: `nana-permission-ids-v6` defines these new IDs. `nana-omnichain-deployers-v6` and `revnet-core-v6` use `LAUNCH_RULESETS` for their deployment flows.
 
 ---
 
@@ -314,7 +324,7 @@ 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. |
+| **Fee-free cashout bypass prevention** | New `_feeFreeSurplusOf` mapping tracks cumulative fee-free intra-terminal payouts per project/token. Capped at remaining balance after outflows including non-zero-tax/feeless cashouts (non-fee-free funds leave first). During zero-tax cashouts, fees are charged up to this tracked amount (then decremented). Cleared on migration. 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
@@ -365,7 +375,7 @@ No changes.
 
 ### 8.10 Solidity Version
 
-All contracts upgraded from `pragma solidity 0.8.23` to `pragma solidity 0.8.26`.
+All contracts upgraded from `pragma solidity 0.8.23` to `pragma solidity 0.8.28`.
 
 ### 8.11 Named Arguments
 

package/README.md

@@ -78,6 +78,8 @@ Hooks are customizable contracts that plug into protocol flows:
 - Surplus allowance usage.
 - Cash outs when the cash out tax rate is above 0%. When the cash out tax rate is 0%, fees apply only up to the project's accumulated fee-free intra-terminal payout surplus (`_feeFreeSurplusOf`) — once that surplus is consumed, subsequent cashouts are fee-free.
 
+`_feeFreeSurplusOf` lifecycle: (a) incremented on fee-free intra-terminal payouts, (b) capped at remaining balance after any outflow (payouts, `useAllowanceOf`, non-zero-tax or feeless cashouts) — non-fee-free funds leave first, (c) consumed (decremented by feeable amount) during zero-tax cashouts, and (d) cleared to zero on terminal migration via `migrateBalanceOf`.
+
 Fees are paid to **project #1** (the fee beneficiary project, minted in the `JBProjects` constructor). Addresses on the `JBFeelessAddresses` allowlist are exempt from fees.
 
 When a ruleset has `holdFees` enabled, fees are held for 28 days before being processed. During this period, if funds are returned to the project via `addToBalanceOf`, held fees can be unlocked and returned.
@@ -98,7 +100,31 @@ Projects can migrate between controllers using the `IJBMigratable` interface. Th
 
 Juicebox V6 separates concerns across specialized contracts that coordinate through a central directory. Projects are represented as ERC-721 NFTs. Each project configures rulesets that dictate how payments, payouts, cash outs, and token minting behave over time.
 
-All contracts use Solidity `0.8.26`.
+All contracts use Solidity `0.8.28`.
+
+```mermaid
+graph TD;
+    User([User / Frontend])
+    User -->|pay / cashOut / sendPayoutsOf| Terminal[JBMultiTerminal]
+    User -->|launchProjectFor / queueRulesetsOf / mintTokensOf| Controller[JBController]
+    Controller -->|reads & writes| Rulesets[JBRulesets]
+    Controller -->|reads & writes| Tokens[JBTokens]
+    Controller -->|reads & writes| Splits[JBSplits]
+    Controller -->|reads & writes| FAL[JBFundAccessLimits]
+    Controller -->|adds feeds to| Prices[JBPrices]
+    Terminal -->|records inflows & outflows| Store[JBTerminalStore]
+    Store -->|reads rulesets from| Rulesets
+    Store -->|reads limits from| FAL
+    Store -->|reads prices from| Prices
+    Terminal -->|distributes payouts via| Splits
+    Directory[JBDirectory] -->|maps projects to| Controller
+    Directory -->|maps projects to| Terminal
+    Controller -->|registers in| Directory
+    Terminal -->|looks up controllers via| Directory
+    Projects[JBProjects] -->|ERC-721 ownership| Directory
+    Permissions[JBPermissions] -->|authorizes calls on| Controller
+    Permissions -->|authorizes calls on| Terminal
+```
 
 ### Core Contracts
 
@@ -151,6 +177,7 @@ All contracts use Solidity `0.8.26`.
 | `JBFees` | Fee calculation helpers. `feeAmountFrom` (forward) and `feeAmountResultingIn` (backward). |
 | `JBFixedPointNumber` | Decimal adjustment between fixed-point number precisions. |
 | `JBMetadataResolver` | Packs and unpacks variable-length `{id: data}` metadata entries with a lookup table. Used by pay/cash-out hooks. |
+| `JBPayoutSplitGroupLib` | External library for payout split-group distribution, called via `DELEGATECALL` from `JBMultiTerminal` to reduce terminal bytecode. Distributes payouts to splits with try-catch per split. |
 | `JBRulesetMetadataResolver` | Packs and unpacks the `uint256 metadata` field on `JBRuleset` into `JBRulesetMetadata`. Bit layout: version (4 bits), reservedPercent (16), cashOutTaxRate (16), baseCurrency (32), 14 boolean flags (1 bit each), dataHook address (160), metadata (14). |
 
 ### Hook Interfaces
@@ -163,6 +190,35 @@ All contracts use Solidity `0.8.26`.
 | `IJBCashOutHook` | Called after a cash out is recorded. Implements `afterCashOutRecordedWith`. |
 | `IJBSplitHook` | Called when processing a split. Implements `processSplitWith`. |
 
+## Risks
+
+This section summarizes known risks and design trade-offs. None of these are unmitigated vulnerabilities -- they are deliberate design decisions with well-understood boundaries.
+
+### Reentrancy
+
+The protocol does not use an explicit `ReentrancyGuard`. Instead, it relies on **state ordering**: all storage writes (balance updates, token mints/burns, payout limit usage) are completed before any external calls (hooks, split payouts, fee processing). This means re-entering a function sees already-updated state, preventing double-spends and double-payouts. The `try-catch` pattern around external calls ensures that hook failures do not leave the protocol in an inconsistent state -- failed calls return funds to the project balance.
+
+### Unbounded Arrays
+
+Several data structures grow without explicit caps:
+
+- **Held fees**: Bounded in practice by the 28-day holding window and auto-cleanup when processed. `processHeldFeesOf` accepts a `count` parameter to limit gas per call.
+- **Splits**: No explicit cap, but the percentage constraint (`SPLITS_TOTAL_PERCENT = 1_000_000_000`) limits the useful number to roughly 300-500. Gas cost scales linearly (~100k gas per split during payout distribution), so very large split groups may cause out-of-gas reverts.
+- **Accounting contexts**: Duplicate prevention limits growth. Realistic maximum is ~100-200 tokens per terminal.
+- **Payout limits / surplus allowances**: Currency ordering constraint limits each group to ~30-50 entries.
+
+### Price Feed DoS
+
+If a Chainlink price feed reverts (stale data, negative price, sequencer downtime on L2), any operation that requires that currency conversion will also revert. This is a **liveness** risk, not a fund-loss risk: no funds are at risk, but payments, payouts, or cash outs denominated in the affected currency pair will be temporarily blocked until the feed recovers. Projects using multiple currencies should be aware of this dependency.
+
+### Weight Cache Requirement
+
+Ruleset weight decay is calculated iteratively. For long-running projects with many elapsed cycles, the iteration count can exceed the block gas limit. The protocol caps iteration at 20,000 cycles per call and provides `updateRulesetWeightCache()` for progressive caching. Projects with very short durations (e.g., 1-second rulesets) that run for extended periods must periodically call this function to keep weight calculations within gas limits.
+
+### Flash Loan Considerations
+
+**C-5 (known, documented)**: Calling `cashOut` with `cashOutCount = 0` when `totalSupply == 0` returns the project's entire surplus. This is a known edge case -- it requires a project to have surplus but zero outstanding tokens, which is not a normal operating state. Projects that accumulate surplus without token holders should be aware of this behavior. The protocol's test suite includes 12 flash-loan attack vectors, all of which confirm that no profit is extractable under normal conditions (tokens minted during a payment are worth at most what was paid).
+
 ## Install
 
 ```bash
@@ -178,5 +234,5 @@ npm install
 | `forge test -vvvv` | Run tests with full traces |
 | `forge fmt` | Format code |
 | `forge fmt --check` | Check formatting (CI lint) |
-| `FOUNDRY_PROFILE=fork forge test` | Run fork tests |
+| `FOUNDRY_PROFILE=CI forge test` | Run fork tests |
 | `forge coverage --match-path "./src/*.sol"` | Generate coverage report |

package/RISKS.md

@@ -12,13 +12,13 @@ What must be true for the system to remain safe:
 - **ERC-20 tokens behave standardly.** `_acceptFundsFor` uses a balance-before/after pattern, which handles fee-on-transfer tokens. However, rebasing tokens that change balances between transactions will cause `balanceOf` in `JBTerminalStore` to diverge from actual terminal holdings. Missing-return-value tokens are handled by `SafeERC20`.
 - **Trusted forwarder is not compromised.** The ERC-2771 forwarder is immutable. If compromised, it can spoof `_msgSender()` for all permission-gated functions across `JBController`, `JBMultiTerminal`, `JBProjects`, `JBPrices`, and `JBPermissions`.
 - **Project #1 terminal remains functional.** If the fee beneficiary project's terminal reverts, `_processFee` catches the error and returns the fee amount to the originating project's balance. This is safe but means fees are silently forgiven during outages.
-- **`OMNICHAIN_RULESET_OPERATOR` is trusted.** This immutable address bypasses owner permission checks for `launchRulesetsFor`, `queueRulesetsOf`, and `setTerminalsOf`. A compromised operator can queue arbitrary rulesets for any project.
+- **`OMNICHAIN_RULESET_OPERATOR` is trusted.** This immutable address bypasses owner permission checks for `launchRulesetsFor` and `queueRulesetsOf`. It can also indirectly set terminals through `launchRulesetsFor`, but cannot call `setTerminalsOf` directly. A compromised operator can queue arbitrary rulesets for any project.
 
 ## 2. Economic Risks
 
 ### Bonding Curve
 
-- **Zero cash out guard.** `cashOutFrom` returns 0 when `cashOutCount == 0` (line 31 early return). Auditors should verify no code path bypasses this guard or reaches the `cashOutCount >= totalSupply` branch (line 37) with both values at 0.
+- **Zero cash out guard.** `cashOutFrom` returns 0 when `cashOutCount == 0` (early return). Auditors should verify no code path bypasses this guard or reaches the `cashOutCount >= totalSupply` branch with both values at 0.
 - **Pending reserved tokens inflate `totalSupply`.** `totalTokenSupplyWithReservedTokensOf()` adds `pendingReservedTokenBalanceOf` to `totalSupply`, reducing per-token cash out value. A project owner who delays calling `sendReservedTokensToSplitsOf()` can suppress cash out values. Auditors should model the magnitude of this effect for projects with large pending reserves.
 - **`mulDiv` rounding.** The bonding curve's subadditivity property (`cashOutFrom(a) + cashOutFrom(b) <= cashOutFrom(a+b)`) can be violated by <0.01% due to floor rounding. Economically insignificant per operation but could accumulate across many small cash outs.
 - **Binary search in `minCashOutCountFor`.** The inverse cash out function uses binary search over `[1, totalSupply]`. For large supplies (>2^128), this is ~128 iterations of `mulDiv` calls. Verify gas cost remains bounded.
@@ -26,11 +26,7 @@ What must be true for the system to remain safe:
 ### Fee Arithmetic
 
 - **Forward vs. backward fee asymmetry.** `feeAmountFrom` (forward) uses `mulDiv(amount, 25, 1000)`. `feeAmountResultingIn` (backward) uses `mulDiv(amount, 1000, 975) - amount`. These are algebraically equivalent but rounding differs. In `_returnHeldFees`, both are used on the same held fee entry (forward to compute `feeAmount`, backward when partially returning). Verify the interplay never undercharges.
-- **Held fee amount mutation.** `_returnHeldFees` mutates `heldFee.amount` in-place via unchecked subtraction (line 1583). If the accounting is off by even 1 wei in the wrong direction, this underflows and corrupts the held fee entry.
-
-### First Cycle Behavior
-
-- **`currentOf()` returns the stored ruleset directly in the first cycle.** The first cycle (`cycleNumber == 1`) uses the original weight with no decay applied. Weight decay via `weightCutPercent` only takes effect from the second cycle onward. This is by design and verified by test (`TestAuditResponseDesignProofs.test_currentOf_firstCycle_returnsOriginalWeight`).
+- **Held fee amount mutation.** `_returnHeldFees` mutates `heldFee.amount` in-place via unchecked subtraction. If the accounting is off by even 1 wei in the wrong direction, this underflows and corrupts the held fee entry.
 
 ### Weight Decay
 
@@ -74,14 +70,10 @@ No `ReentrancyGuard` is used. The system relies on state ordering and the `Inade
 ### Permission System
 
 - **ROOT (ID 1) grants all permissions.** Including permissions not yet defined. Future permission IDs automatically fall under ROOT.
-- **ROOT cannot be set for wildcard `projectId = 0`.** The actual enforcement in `setPermissionsFor` is: if the caller is not the account itself, they must have ROOT for the target project, AND they cannot set ROOT for others, AND they cannot set any permissions on the wildcard project. ROOT holders for a specific project can set non-ROOT permissions for operators on that project. Auditors should verify the exact boundary -- particularly whether a ROOT operator on project X can escalate to ROOT on project Y through any indirect path.
+- **ROOT + wildcard (`projectId = 0`) is allowed for self-grants only.** An account can grant its own operator ROOT on the wildcard project, giving that operator god-mode across all of the account's projects. This is powerful but legitimate — the account owner is explicitly choosing to delegate full control. However, a third-party caller who holds ROOT for a specific project **cannot** grant ROOT to others or set any permissions on the wildcard project on someone else's behalf. This prevents ROOT operators from escalating their own privileges beyond what the account owner originally granted. Auditors should verify that no indirect path allows a ROOT operator on project X to escalate to ROOT on project Y without the account owner's direct action.
 - **Empty permission arrays pass `hasPermissions`.** By design (vacuous truth). Any caller that expects "the operator has at least one of these permissions" must validate the array is non-empty.
 - **`OMNICHAIN_RULESET_OPERATOR` bypass.** This immutable address can `launchRulesetsFor`, `queueRulesetsOf`, and set terminals for any project without owner permission. The trust assumption is that this operator only queues rulesets that the omnichain deployer's logic permits. If this address is an EOA or an upgradeable contract, it is a single point of failure for all projects.
 
-### Splits GroupId Namespace
-
-- **GroupId namespace overlap between terminals and token contracts is prevented.** Terminals use `uint160(tokenAddress)` as the `groupId` for payout split groups -- these have zero upper 96 bits. The self-auth path in `setSplitGroupsOf` now requires the upper 96 bits of the `groupId` to be non-zero (in addition to the lower 160 bits matching `msg.sender`). This means bare-address groupIds (upper 96 bits = 0) are protocol-reserved and always require controller authorization. Without this restriction, an accepted token contract could call `setSplitGroupsOf` to overwrite the terminal's payout splits for its own address. The 721 hook is unaffected since it uses `hookAddress | tierId << 160` (non-zero upper bits).
-
 ### Migration
 
 - **Controller migration** requires `allowSetController` in the current ruleset. During migration, `JBController.migrate()` reverts if there are pending reserved tokens. An attacker cannot front-run migration to inflate pending reserves (they'd need mint permission), but a project with organic pending reserves must distribute them first.
@@ -131,6 +123,8 @@ No `ReentrancyGuard` is used. The system relies on state ordering and the `Inade
 - **Data hooks are called during previews.** `previewPayFor` and `previewCashOutFrom` invoke `beforePayRecordedWith` and `beforeCashOutRecordedWith` on data hooks. A reverting data hook causes the preview to revert. A gas-consuming hook can cause the preview to run out of gas.
 - **Store previews take an explicit terminal parameter.** `JBTerminalStore.previewPayFrom` and `previewCashOutFrom` take an explicit `terminal` address for balance/surplus lookups. Callers must pass a registered terminal to get correct results. The terminal-level functions (`JBMultiTerminal.previewPayFor` / `previewCashOutFrom`) handle this automatically by passing `address(this)`.
 - **No state modification risk.** Preview functions cannot change balances, mint/burn tokens, or consume limits. They are safe to call from any context.
+- **Preview-execution divergence.** Preview functions and their corresponding real operations share computation logic but execute in different contexts. `previewPayFor` calls `STORE.previewPayFrom` which invokes the data hook's `beforePayRecordedWith` via `staticcall`. The real `pay` path invokes the same hook but state changes between preview and execution (other payments, cash outs, ruleset transitions) can change the data hook's response. Callers should treat preview results as estimates, not guarantees — especially for projects with stateful data hooks.
+- **Gas griefing via data hooks in previews.** Since `previewPayFor` and `previewCashOutFrom` invoke data hooks, a gas-expensive data hook can make preview calls prohibitively expensive. This affects frontends and indexers that rely on preview functions for quote display. Unlike the real operations (which have economic incentive to complete), preview calls have no built-in gas limit on the data hook invocation.
 
 ## 7. Integration Risks
 
@@ -143,15 +137,19 @@ No `ReentrancyGuard` is used. The system relies on state ordering and the `Inade
 
 ### Permit2 Interactions
 
-- `_acceptFundsFor` tries direct ERC-20 `transferFrom` first (if allowance is sufficient), then falls back to Permit2. The Permit2 `permit` call is wrapped in try-catch -- failure emits an event but doesn't revert the payment.
-- `_transferFrom` for outbound transfers also falls back to Permit2 if direct allowance is insufficient. This means outbound transfers (to beneficiaries, split hooks) may unexpectedly use Permit2 state.
-- The `uint160` cast on line 1897 of `JBMultiTerminal.sol` limits Permit2 transfers to `type(uint160).max`. Amounts above this revert with `OverflowAlert`.
+- **Permit2 is only used for inbound transfers.** `_acceptFundsFor` tries direct ERC-20 `transferFrom` first (if allowance is sufficient), then falls back to Permit2. The Permit2 `permit` call is wrapped in try-catch -- failure emits an event but doesn't revert the payment.
+- **Outbound transfers never use Permit2.** All outbound `_transferFrom` calls pass `from: address(this)`, which takes the direct transfer path (`safeTransfer` for ERC-20s, `Address.sendValue` for native token) and returns before reaching the Permit2 fallback. The Permit2 fallback in `_transferFrom` only exists for the inbound case where `from` is the payer (`_msgSender()`).
+- The `uint160` cast in `JBMultiTerminal._acceptFundsFor` limits Permit2 transfers to `type(uint160).max`. Amounts above this revert with `OverflowAlert`.
 
 ### Cross-Terminal Surplus Aggregation
 
 - `JBSurplus.currentSurplusOf` calls `terminal.currentSurplusOf()` on each terminal. These are external view calls with no gas limit. A malicious or gas-expensive terminal can cause this aggregation to revert, blocking cash outs for any project that has `useTotalSurplusForCashOuts` enabled and uses that terminal. When `useTotalSurplusForCashOuts` is false, surplus is computed internally by the store for only the reclaimed token, avoiding cross-terminal external calls.
 - The surplus calculation converts each terminal's balance to a common currency via price feeds. Rounding accumulates across terminals. With N terminals and M tokens each, there are N*M price conversions, each with up to 1 wei of rounding error.
 
+### `addToBalanceOf` with Arbitrary Metadata
+
+- `addToBalanceOf` accepts arbitrary `metadata` which is not validated by the terminal or store. The metadata is passed through to `afterAddToBalanceRecordedWith` callbacks. If a project's data hook or terminal extension interprets this metadata, malformed metadata could cause unexpected behavior. The core protocol ignores metadata in `addToBalanceOf` — it only affects hook processing.
+
 ### `recordAddedBalanceFor` Access Control
 
 - `JBTerminalStore.recordAddedBalanceFor` has **no access control**. Any address can call it. The balance is keyed by `msg.sender` (the terminal address), so only a terminal can inflate its own recorded balance. This is safe as long as all terminals correctly track their actual holdings. A buggy or malicious terminal implementation could call `recordAddedBalanceFor` without actually receiving tokens, inflating the recorded balance above actual holdings.
@@ -188,10 +186,5 @@ These should hold at all times and are the most productive targets for formal ve
 ### No Flash-Loan Profit
 - `pay() + cashOutTokensOf()` in the same transaction should never be profitable after fees. The 2.5% fee should make single-block round-trips unprofitable. Verify this holds when data hooks modify weights or cash out parameters.
 
-### Same-Terminal Fee Exemption
-
-- **Payouts between projects on the same terminal are fee-exempt by design.** When `executePayout` sends funds to a split's project that uses the same `JBMultiTerminal`, no fee is charged — the payout is routed via `addToBalanceOf` (internal accounting) rather than requiring an external transfer. Fees only apply when funds leave the terminal (sent to an EOA beneficiary or a different terminal). This is intentional: fees protect against fund egress, not intra-terminal accounting moves. Verified by test (`TestAuditResponseDesignProofs.test_sameTerminal_payoutNoFee`).
-- **Fee-free surplus tracking prevents round-trip fee bypass.** When a project receives a fee-free intra-terminal payout, `_feeFreeSurplusOf[projectId][token]` is incremented by the payout amount. During cashout with `cashOutTaxRate == 0`, the 2.5% fee is applied only up to this accumulated surplus — then decremented. Once depleted, subsequent cashouts are fee-free again. This scopes the fee precisely to the fee-free inflow: a 1 wei griefing payout only costs the victim fees on 1 wei, not their entire balance. Without this, an attacker could route payouts through a pass-through project with `cashOutTaxRate=0` and cash out fee-free. When `cashOutTaxRate != 0`, the fee applies to the full reclaim amount regardless of surplus. Verified by 7 tests in `TestFeeFreeCashOutBypass.sol`.
-
 ### Held Fee Integrity
 - `sum(heldFee.amount for active entries) + sum(processed fees) == total fees ever taken with shouldHoldFees=true`. Active entries are those from `_nextHeldFeeIndexOf` to end of array. Verify `_returnHeldFees`' in-place mutation of `heldFee.amount` preserves this invariant.