@bananapus/core-v6 0.0.37 → 0.0.38

package/ADMINISTRATION.md

@@ -1,103 +0,0 @@
-# Administration
-
-## At A Glance
-
-| Item | Details |
-| --- | --- |
-| Scope | Core Juicebox V6 control plane: directory, controller, terminals, permissions, prices, and global protocol switches |
-| Control posture | Mixed protocol-owner, project-owner, delegated-operator, controller, and terminal control |
-| Highest-risk actions | Controller migration, terminal migration, token binding, price-feed installation, and broad permission grants |
-| Recovery posture | Project-local mistakes may be fixable if rulesets allow it; immutable infra mistakes usually require replacement and migration |
-
-## Purpose
-
-`nana-core-v6` is the main control plane in the stack. It mixes protocol-owned contracts, project-local ownership, delegated operators through `JBPermissions`, and ruleset flags that allow or block changes. This file explains who can still change project behavior after core is live.
-
-## Control Model
-
-- Protocol-wide `Ownable` surfaces exist on `JBDirectory`, `JBProjects`, `JBPrices`, and `JBFeelessAddresses`.
-- Project-local control comes from the project NFT owner in `JBProjects`.
-- Fine-grained operator delegation comes from `JBPermissions`.
-- Controllers and terminals become privileged system callers once the directory points to them.
-- The current ruleset can further allow or deny owner or operator actions.
-
-## Roles
-
-| Role | How Assigned | Scope | Notes |
-| --- | --- | --- | --- |
-| Project owner | `JBProjects.ownerOf(projectId)` | Per project | Main human control surface |
-| Project operator | `JBPermissions` grant | Per project or wildcard | Can be narrow or dangerously broad |
-| Controller | `JBDirectory.controllerOf(projectId)` | Per project | Manages rulesets, token setup, splits, and fund-access config |
-| Terminal | `JBDirectory` terminal set | Per project | Moves funds through `JBTerminalStore` and terminal entrypoints |
-| Protocol owner | `Ownable(owner)` on protocol-wide contracts | Global | Different contracts can have different owners |
-| Omnichain ruleset operator | `JBController` constructor immutable | Global or broad | Bypasses some owner checks for synchronized ruleset flows |
-
-## Privileged Surfaces
-
-High-value admin functions include:
-
-- `JBDirectory.setControllerOf(...)`, `setTerminalsOf(...)`, `setPrimaryTerminalOf(...)`
-- `JBController.queueRulesetsOf(...)`, `launchRulesetsFor(...)`, `setSplitGroupsOf(...)`, `deployERC20For(...)`, `setTokenFor(...)`, `setUriOf(...)`, `addPriceFeedFor(...)`
-- `JBMultiTerminal.useAllowanceOf(...)`, `migrateBalanceOf(...)`, `cashOutTokensOf(...)` when permission-gated by the holder or delegated authority
-- `JBPermissions.setPermissionsFor(...)`
-- `JBPrices.addPriceFeedFor(...)` for protocol defaults or project-local feeds
-- `JBFeelessAddresses.setFeelessAddress(...)`
-- `JBProjects.setTokenUriResolver(...)`
-
-The practical split is simple:
-
-- protocol owners change global infrastructure or defaults
-- project owners and operators change project configuration
-- controllers and terminals act with the authority core gives them
-
-## Immutable And One-Way Decisions
-
-- Default or project-specific price feeds are write-once for a given pair.
-- ERC-20 token binding for a project is effectively one-time.
-- The fee beneficiary project ID inside `JBMultiTerminal` is hardcoded.
-- Constructor immutables on controller, directory, terminal, store, prices, and tokens cannot be patched.
-
-## Operational Notes
-
-- Use narrow project-scoped permissions instead of wildcard or ROOT permissions when possible.
-- Check whether the active ruleset allows the change before assuming the owner or operator can make it.
-- Treat controller migration, terminal migration, token deployment, and price-feed installation as high-blast-radius control-plane changes.
-- Read both the permission check and the current ruleset flags before concluding an action is allowed.
-- Keep fee-route and payout-path failure semantics in mind. Some failures restore project balance instead of trapping funds.
-
-## Machine Notes
-
-- Do not infer authority from project ownership alone. Many paths also depend on the active ruleset and permission bitmap.
-- Treat `JBDirectory`, `JBController`, `JBMultiTerminal`, `JBPermissions`, `JBPrices`, `JBFeelessAddresses`, and `JBProjects` as the minimum control-plane source set.
-- If a controller, terminal, or price-feed action is not backed by the exact current directory entry, stop and resolve the mismatch first.
-- If a permission is not named explicitly in the call path, inspect the contract check before assuming delegated authority exists.
-- If a fee route or split payout failed, check whether core restored balance or left a retry path before calling it a permanent loss.
-
-## Recovery
-
-- Wrong immutable infrastructure usually means deploying a new controller, terminal, store, or price layer and then migrating.
-- Wrong project-local config can often be corrected if the current ruleset still allows it.
-- Wrong wildcard permissions are fixed by updating the permission bitmap, but they are dangerous because of what can happen before revocation.
-- Some fee-route and payout-route failures are recoverable in place because core prefers liveness over trapped funds.
-
-## Admin Boundaries
-
-- Protocol owners cannot directly rewrite project economics without going through the contracts and ruleset constraints that enforce those changes.
-- Project owners cannot bypass immutable constructor references or rewrite existing price-feed entries.
-- Controllers and terminals only have the authority given by the directory and core contracts.
-- Nobody can change the hardcoded fee beneficiary or patch immutable deployment mistakes in place.
-
-## Source Map
-
-- `src/JBDirectory.sol`
-- `src/JBController.sol`
-- `src/JBMultiTerminal.sol`
-- `src/JBPermissions.sol`
-- `src/JBPrices.sol`
-- `src/JBFeelessAddresses.sol`
-- `src/JBProjects.sol`
-- `test/units/static/JBController/`
-- `test/units/static/JBDirectory/`
-- `test/units/static/JBMultiTerminal/`
-- `test/units/static/JBPermissions/`
-- `test/units/static/JBPrices/`

package/ARCHITECTURE.md

@@ -1,133 +0,0 @@
-# Architecture
-
-## Purpose
-
-`nana-core-v6` is the root of the V6 stack. It owns project identity, rulesets, permissions, treasury balances, token issuance, fee behavior, payout limits, and the hook interfaces that extension repos use.
-
-If a change affects accounting, token supply, fees, terminal routing, or permission semantics, this repo is the source of truth.
-
-## System Overview
-
-`JBController`, `JBMultiTerminal`, and `JBTerminalStore` form the main execution and accounting path. `JBDirectory`, `JBRulesets`, `JBProjects`, `JBTokens`, `JBPermissions`, `JBSplits`, and related contracts provide routing, identity, and shared state for downstream repos.
-
-`JBTerminalStore` is terminal-scoped through `msg.sender`, so each terminal tracks its own balances and usage while sharing the same ruleset and price surfaces. Hooks can change economics or add side effects, but they should not create a second ledger.
-
-## Core Invariants
-
-- Preview functions should stay aligned with the state-changing functions they mirror.
-- Data hooks run before settlement and may change economics. Pay and cash-out hooks run after settlement.
-- Reserved tokens and other pending supply affect supply-sensitive math before distribution.
-- Terminal balances, fee accounting, reclaim math, and surplus calculations must agree.
-- Fee logic taxes value leaving the system, not every internal rebalance.
-- Rulesets are time-ordered and approval-aware, and downstream deployers depend on predictable ID progression.
-- Permission checks are protocol safety checks, not just UI hints.
-
-## Modules
-
-| Module | Responsibility | Notes |
-| --- | --- | --- |
-| `JBMultiTerminal` | Payment, cash-out, payout, allowance, and fee entrypoints | Execution surface |
-| `JBTerminalStore` | Shared accounting and preview math | Economic source of truth |
-| `JBController` | Launch, queue rulesets, mint, burn, and update split groups | Supply and configuration |
-| `JBDirectory`, `JBRulesets` | Project routing and time-based ruleset lifecycle | Coordination layer |
-| `JBProjects`, `JBTokens`, `JBERC20` | Identity and token surfaces | Ownership and tokenization |
-| `JBPermissions`, `JBSplits`, `JBFundAccessLimits`, `JBPrices` | Shared authorization and configuration state | Cross-repo dependencies |
-
-## Trust Boundaries
-
-- This repo owns the canonical balance and supply transitions.
-- Hook repos may change inputs and post-settlement behavior, but they should not replace the core ledger.
-- External price feeds, Permit2, and ERC-20 behavior matter, but accounting truth still lives here.
-
-## Critical Flows
-
-### Payment
-
-```text
-terminal receives funds
-  -> terminal store reads the active ruleset and optional data hooks
-  -> before-pay data hook can change weight and return pay-hook specs
-  -> terminal store records the payment in the terminal-scoped ledger
-  -> controller mints beneficiary tokens and accrues reserved tokens
-  -> pay hooks run after settlement
-```
-
-### Cash Out
-
-```text
-holder requests redemption
-  -> terminal store reads the current ruleset, balances, and supply inputs
-  -> before-cash-out data hook can change reclaim inputs and hook specs
-  -> terminal store records the cash out in the terminal-scoped ledger
-  -> controller burns tokens
-  -> terminal pays reclaim value and routes protocol fees
-  -> cash-out hooks run after settlement
-```
-
-### Launch And Queue Rulesets
-
-```text
-owner, operator, or omnichain ruleset operator
-  -> controller launches or queues rulesets
-  -> launch also sets the controller in the directory and configures terminals
-  -> rulesets become the source of truth for later pay, cash-out, and admin constraints
-```
-
-### Payouts And Allowances
-
-```text
-authorized caller
-  -> consumes payout limits or surplus allowances
-  -> funds move to splits, projects, hooks, or direct recipients
-  -> same-terminal project payouts stay inside terminal accounting and may add fee-free surplus
-```
-
-## Accounting Model
-
-This repo owns the canonical ledger for balances, fees, supply-sensitive reclaim math, payout limits, allowances, reserved tokens, and preview calculations. Other repos may wrap or influence these values, but they should not duplicate them.
-
-`JBTerminalStore` keeps terminal balances, payout-limit usage, and surplus-allowance usage. Those reset boundaries are not the same:
-
-- payout-limit usage is tracked by ruleset cycle number
-- surplus-allowance usage is tracked by `ruleset.id`
-
-If a duration-based ruleset auto-cycles without a new ruleset ID, payout-limit usage resets but allowance usage does not.
-
-## Security Model
-
-- Review `JBMultiTerminal`, `JBTerminalStore`, and `JBController` as one pipeline.
-- `JBTerminalStore` uses shared logic with terminal-scoped state. Misreading that split leads to bad accounting assumptions.
-- Small changes in fee or surplus logic can affect every downstream repo.
-- Same-terminal project payouts, fee-free surplus capping, and migration cleanup are coupled.
-- `allowOwnerMinting` is not a universal mint kill switch. Other allowed paths can still mint.
-- Hook ordering and preview-execution alignment are ongoing maintenance requirements.
-
-## Safe Change Guide
-
-- Trace both the preview path and the state-changing path for any nontrivial change.
-- Read downstream hook repos before changing hook metadata or interface expectations.
-- Keep fee logic, balance logic, reclaim math, and surplus math in sync.
-- If you change same-terminal payouts between projects, re-check self-pay reverts, fee-free surplus accumulation, and post-pay caps.
-- If you change ruleset rollover semantics, re-check which counters reset on cycle progression versus new ruleset IDs.
-- If permissions change, update shared docs and downstream assumptions at the same time.
-
-## Canonical Checks
-
-- fee-free surplus and same-terminal payout behavior:
-  `test/TestFeeFreeCashOutBypass.sol`
-- migration and terminal-accounting continuity:
-  `test/TestTerminalMigration.sol`
-- ruleset ordering and transition behavior:
-  `test/RulesetTransitions.t.sol`
-
-## Source Map
-
-- `src/JBController.sol`
-- `src/JBMultiTerminal.sol`
-- `src/JBTerminalStore.sol`
-- `src/JBDirectory.sol`
-- `src/JBRulesets.sol`
-- `src/JBPermissions.sol`
-- `test/TestFeeFreeCashOutBypass.sol`
-- `test/TestTerminalMigration.sol`
-- `test/RulesetTransitions.t.sol`

package/AUDIT_INSTRUCTIONS.md

@@ -1,139 +0,0 @@
-# Audit Instructions
-
-This is the core Juicebox V6 protocol. Most ecosystem invariants eventually reduce to this repo.
-
-## Audit Objective
-
-Find issues that:
-
-- break terminal solvency or internal accounting
-- let projects extract more than payout or surplus-allowance limits
-- miscompute payment minting, reserved tokens, or cash-out reclaim amounts
-- corrupt ruleset transitions, approvals, or decay behavior
-- bypass the permission model, migrations, or fee lifecycle
-
-## Scope
-
-In scope:
-
-- all Solidity under `src/`
-- deployment scripts in `script/`
-- price-feed setup and periphery contracts under `src/periphery/`
-
-Especially critical contracts:
-
-- `JBMultiTerminal`
-- `JBTerminalStore`
-- `JBController`
-- `JBRulesets`
-- `JBTokens`
-- `JBPermissions`
-- `JBPrices`
-- `JBSplits`
-- `JBFundAccessLimits`
-
-## Start Here
-
-For the fastest serious review, read in this order:
-
-- `JBTerminalStore`
-- `JBMultiTerminal`
-- `JBController`
-- `JBRulesets`
-- `JBPermissions`
-- `JBPrices`
-
-That order mirrors how most high-severity issues appear:
-
-- accounting is computed
-- funds move
-- tokens mint or burn
-- permissions and price context determine whether the move is allowed
-
-## Security Model
-
-Core roles:
-
-- `JBMultiTerminal`: holds funds and executes pay, payout, cash-out, allowance, and fee-processing flows
-- `JBTerminalStore`: owns accounting and surplus logic
-- `JBController`: owns project lifecycle, token mint and burn, and permission-sensitive operations
-- `JBRulesets`: stores current and queued economic parameters
-- `JBTokens`: handles ERC-20 and credit accounting
-- `JBPermissions`: provides the access-control backbone
-
-Extension points:
-
-- data hooks
-- pay hooks
-- cash-out hooks
-- split hooks
-- approval hooks
-
-Ordering to keep in mind:
-
-- the store records accounting before terminal fulfillment is finished
-- controller mint and burn operations happen inside terminal flows, not in a separate settlement layer
-- hooks can turn a simple pay or cash-out into a multi-contract flow
-
-## Roles And Privileges
-
-| Role | Powers | How constrained |
-|------|--------|-----------------|
-| Project owner and operators | Configure rulesets, limits, routing, and permissions | Must stay inside the explicit permission model |
-| Terminal | Hold funds and execute settlement | Must stay solvent relative to internal accounting |
-| Controller | Mint, burn, and manage project lifecycle | Must not bypass project-scoped authorization |
-| Hooks and splits | Extend pay and cash-out behavior | Must not make previews and accounting irreconcilable |
-
-## Integration Assumptions
-
-| Dependency | Assumption | What breaks if wrong |
-|------------|------------|----------------------|
-| Price feeds | Currency conversions are fresh and coherent | Cross-currency flows misprice |
-| Hook ecosystem | External hooks obey documented interfaces | Settlement becomes unsafe after control transfer |
-| Directory and migration surfaces | Canonical routing changes are authentic | Funds or permissions shift to the wrong place |
-
-## Critical Invariants
-
-1. Terminal solvency  
-   Internal balances and held-fee obligations must reconcile with actual terminal token balances.
-2. No over-withdrawal  
-   Payouts and allowance usage must never exceed configured per-cycle limits.
-3. Cash-out correctness  
-   Surplus, total supply, tax rate, fee treatment, and hook overrides must combine into the intended reclaim amount.
-4. Ruleset integrity  
-   The active ruleset and any fallback or cycling behavior must match exact timing and approval-hook semantics.
-5. Token accounting consistency  
-   Credits, ERC-20 total supply, reserved token balance, and burn/mint paths must stay coherent.
-6. Privilege containment  
-   Permissions, wildcard grants, controller migration, and terminal routing must not allow unauthorized control or fund movement.
-7. Held-fee correctness  
-   Deferred fees must not be accidentally forgiven, duplicated, or charged to the wrong place.
-8. Preview coherence  
-   `previewPayFor` and `previewCashOutFrom` should not drift from execution in ways downstream repos can exploit.
-
-## Attack Surfaces
-
-- `pay`, `cashOutTokensOf`, `sendPayoutsOf`, and `useAllowanceOf`
-- `preview*` paths when downstream repos treat them as execution truth
-- held-fee lifecycle and `_processFee`
-- surplus aggregation across terminals
-- controller migration and terminal migration
-- `setPermissionsFor` and wildcard semantics
-
-Replay these sequences:
-
-1. `pay` with a data hook that changes weight or hook specs and then reenters through a pay hook
-2. `cashOutTokensOf` when cross-terminal surplus and `useTotalSurplusForCashOuts` matter
-3. `sendPayoutsOf` into splits that route to another project, hook, or failing beneficiary
-4. held-fee accumulation followed by migration or balance depletion
-5. permission grants involving operators, wildcard project IDs, or later controller changes
-
-## Accepted Risks Or Behaviors
-
-- Hooks are intentionally powerful. Safety comes from clear ordering and bounded trust, not from avoiding composition.
-
-## Verification
-
-- `npm install`
-- `forge build`
-- `forge test`

package/RISKS.md

@@ -1,215 +0,0 @@
-# Juicebox Core Risk Register
-
-This file covers the main accounting, permission, and liveness risks in the core protocol contracts that the rest of V6 builds on.
-
-## How To Use This File
-
-- Read `Priority risks` first. Those are the failures with the widest blast radius.
-- Use the later sections when you need detail on accounting, reentrancy, access control, previews, or integrations.
-- Treat `Invariants to verify` as core properties, not optional test ideas.
-
-## Priority Risks
-
-| Priority | Risk | Why it matters | Primary controls |
-|----------|------|----------------|------------------|
-| P0 | Core accounting corruption | Terminal, store, and controller accounting define balances, surplus, fees, and supply for the whole ecosystem. | Invariant tests, preview/settlement alignment, and conservative integrations. |
-| P0 | Permission or migration mistakes | Controllers, terminals, and operators can redirect authority or value if checks or sequencing are wrong. | Permission review, migration tests, and scrutiny of wildcard or root-like authority. |
-| P1 | Preview or settlement drift | Hooks and routers often depend on previews being close to execution. | Preview analysis, regression tests, and downstream composition review. |
-
-## 1. Trust Assumptions
-
-- **Hooks are not exploiting reentrancy.** Core does not use `ReentrancyGuard`. Safety depends on call ordering and the `JBTerminalStore_InadequateTerminalStoreBalance` backstop.
-- **Data hooks are highly trusted.** A data hook can change payment weight, cash-out tax rate, `effectiveTotalSupply`, `effectiveCashOutCount`, and hook-forwarding amounts. The protocol only bounds the final amounts.
-- **Price feeds are honest enough.** Surplus, payout conversions, and allowance math depend on `JBPrices`. Stale or manipulated feeds misprice the system.
-- **Accepted ERC-20s behave like standard tokens.** Inbound fee-on-transfer handling is safer than outbound handling. Rebasing or nonstandard outbound behavior can still break accounting assumptions.
-- **Accepted tokens are not actively adversarial.** Core does not harden against tokens that reenter or distort balance observations during transfer.
-- **The trusted forwarder is not compromised.** If it is, `_msgSender()` can be spoofed across permission-gated contracts.
-- **Project `#1` fee routing stays live enough.** If fee processing into project `#1` fails, core favors liveness and returns value to the originating project instead of trapping it. That can forgive fees.
-- **`OMNICHAIN_RULESET_OPERATOR` is trusted.** This address can bypass some owner checks for ruleset flows and is a broad trust point.
-
-## 2. Economic Risks
-
-### Bonding Curve
-
-- **Zero cash-out guard.** `cashOutFrom` returns `0` when `cashOutCount == 0`. Verify no path bypasses that guard.
-- **Pending reserved tokens lower cash-out value.** `totalTokenSupplyWithReservedTokensOf()` includes `pendingReservedTokenBalanceOf`, which can reduce per-token reclaim value until reserves are distributed.
-- **External token supply only affects that project.** If a project uses `setTokenFor(...)`, the external token's `totalSupply()` feeds that project's cash-out math.
-- **`mulDiv` rounding exists.** Split cash outs can differ slightly from a combined cash out because of floor rounding.
-- **`minCashOutCountFor` uses binary search.** Large supplies increase loop count. Gas should stay bounded.
-
-### Fee Arithmetic
-
-- **Forward and backward fee math round differently.** `feeAmountFrom` and `feeAmountResultingIn` are close but not identical under rounding. Their interaction matters in held-fee paths.
-- **Held fee entries are mutated in place.** If the accounting is off by even one unit in the wrong direction, `_returnHeldFees` can corrupt the entry.
-
-### Weight Decay
-
-- **Stale weight cache can block a project.** Short-duration rulesets with nonzero `weightCutPercent` can hit `WeightCacheRequired` after 20,000 elapsed cycles (`_WEIGHT_CUT_MULTIPLE_CACHE_LOOKUP_THRESHOLD`). Projects approaching this limit must call `updateRulesetWeightCache()` to pre-cache decayed weights.
-- **Weight-cache correctness matters more than overflow.** Overflow is already bounded at queue time. The real risk is stale or wrongly-updated cache state.
-
-### Surplus Manipulation
-
-- **Cross-terminal surplus is a trust boundary.** When `useTotalSurplusForCashOuts` is enabled, one terminal can price a cash out using value reported by other terminals.
-- **Cross-terminal price-feed mismatch changes reclaim values.** If feeds differ or go stale across terminals, aggregated surplus can be wrong.
-
-## 3. Reentrancy Surface
-
-Core does not use `ReentrancyGuard`. It relies on state ordering plus `InadequateTerminalStoreBalance` as the last balance-extraction backstop.
-
-### External Call Map
-
-| Function | State Changes Before External Call | External Calls | Risk |
-|----------|-----------------------------------|----------------|------|
-| `_pay` | `STORE.recordPaymentFrom`, `controller.mintTokensOf` | Pay hooks | LOW |
-| `_cashOutTokensOf` | `STORE.recordCashOutFor`, `controller.burnTokensOf`, beneficiary transfer | Cash-out hooks, then fee processing | MEDIUM |
-| `executePayout` | `STORE.recordPayoutFor` already consumed payout limit | Split hooks, terminal pay/addToBalance | MEDIUM |
-| `processHeldFeesOf` | Held-fee entry deleted and index advanced | `_processFee` -> `this.executeProcessFee` -> `terminal.pay` | LOW |
-| `_sendReservedTokensToSplitsOf` | Pending reserved balance zeroed, tokens minted | Split hooks, terminal payments | LOW |
-| `_useAllowanceOf` | `STORE.recordUsedAllowanceOf` | Fee processing, beneficiary transfer | LOW |
-| `migrateBalanceOf` | `STORE.recordTerminalMigration` | `to.addToBalanceOf` | LOW |
-
-### Cross-Function Reentrancy To Explore
-
-- **Pay hook -> `cashOutTokensOf`.** The hook sees post-payment balance and post-mint supply.
-- **Cash-out hook -> `pay`.** The hook runs after burn and payout but before fee processing completes.
-- **Split hook -> `pay` on the same project.** Core now reverts same-project intra-terminal self-pay minting, but the path is still worth checking.
-- **Reserved-token split hook reentry.** Hooks see post-mint state after pending reserved balance is zeroed.
-- **Fee processing reentry.** `_processFee` makes an external fee payment into project `#1`; hook behavior there still matters.
-
-### Key Backstop
-
-`JBTerminalStore_InadequateTerminalStoreBalance` should stop any path from pulling more than the terminal's recorded balance. Auditors should verify no caller can inflate that recorded balance without the terminal actually holding the funds.
-
-## 4. Access Control
-
-### Permission System
-
-- **ROOT grants all permissions.** That includes permissions added in the future.
-- **ROOT plus wildcard is allowed only for self-grants.** An account can delegate broad power over its own projects, but third parties should not be able to escalate into it.
-- **Empty permission arrays pass `hasPermissions`.** Callers must check for non-empty arrays if that matters to their logic.
-- **`OMNICHAIN_RULESET_OPERATOR` is a broad bypass.** It can queue or launch rulesets for any project.
-
-### Directory Terminal Addition
-
-- **`setPrimaryTerminalOf` can also add a terminal.** When the terminal is not already installed, the call must satisfy `ADD_TERMINALS` as well as the primary-terminal permission.
-
-### Migration
-
-- **Controller migration depends on ruleset permission.** `allowSetController` must be active, and migration fails if reserved tokens are still pending.
-- **Terminal migration also depends on ruleset permission.** Held fees are not migrated, and migration into a non-feeless terminal charges the normal protocol fee.
-- **Directory updates are high-impact.** `setTerminalsOf` and `setControllerOf` can redirect a project's fund and authority flow.
-
-### Ruleset Queuing
-
-- Only the current controller can call `RULESETS.queueFor()`.
-- The controller lets the owner, an allowed operator, or `OMNICHAIN_RULESET_OPERATOR` queue rulesets.
-- For `duration = 0` projects, a queued ruleset can take effect immediately.
-
-## 5. DoS Vectors
-
-### Unbounded Arrays
-
-| Array | Growth Mechanism | Cleanup | Risk |
-|-------|-----------------|---------|------|
-| `_heldFeesOf[projectId][token]` | Each held-fee payout appends | Index pointer skips processed entries | MODERATE |
-| `splits[]` | Set by project owner per ruleset | Replaced wholesale | MODERATE |
-| `_accountingContextsOf[projectId]` | `addAccountingContextsFor` append-only | Never shrinks | LOW |
-| Payout limits / surplus allowances | Set per ruleset | Replaced per ruleset | LOW |
-| `_terminalsOf[projectId]` | `setTerminalsOf` replace-only | Replaced | LOW |
-
-### Price Feed Reverts
-
-- Stale or incomplete Chainlink data can block multi-currency operations.
-- L2 sequencer downtime can also block feeds behind a sequencer-check wrapper.
-- Single-currency projects are unaffected when they do not need conversion.
-- Price feeds are immutable once set in `JBPrices`.
-
-### Approval Hook Griefing
-
-- A reverting approval hook is caught and treated as failed approval.
-- A gas-burning approval hook can still DoS `currentOf()` by exhausting gas.
-- Repeated approval-hook rejection at a ruleset boundary can create complex fallback behavior that needs testing.
-
-### Other DoS Surfaces
-
-- Failed split payouts consume payout limit even when value is returned to project balance.
-- `addAccountingContextsFor` is append-only, so projects that add many contexts over time can make some loops more expensive.
-
-## 6. Preview Functions
-
-`JBMultiTerminal.previewPayFor`, `JBMultiTerminal.previewCashOutFrom`, and `JBController.previewMintOf` are read-only simulations of state-changing operations.
-
-- **Previews call data hooks.** A reverting or gas-heavy hook can break previews.
-- **Store previews require the correct terminal input.** Passing the wrong terminal gives the wrong answer.
-- **Previews do not mutate state.** They cannot consume limits, move funds, or mint and burn tokens.
-- **Preview and execution can still drift.** Shared logic helps, but state can change between calls and hooks can be stateful.
-- **Some read-only surplus views are not hook-aware.** `currentReclaimableSurplusOf` and `currentTotalReclaimableSurplusOf` intentionally skip data hooks.
-
-## 7. Integration Risks
-
-### Non-Standard ERC-20s
-
-- **Fee-on-transfer tokens.** Inbound handling is safer than outbound handling. Outbound transfer fees can leave store accounting higher than real holdings.
-- **Reentrant transfer hooks.** Core treats them as an accepted integration risk, not a hardened invariant.
-- **Rebasing tokens.** Positive or negative rebases can desync terminal balances from store balances.
-- **Blocklist tokens.** Beneficiary-specific transfer failures can revert user cash outs or return payout value to the project.
-- **Low-decimal tokens.** Fixed-point conversions can lose meaningful precision.
-
-### Permit2 Interactions
-
-- Permit2 is only used for inbound transfers.
-- Outbound transfers never rely on Permit2.
-- The `uint160` cast in `_acceptFundsFor` caps Permit2 transfer size.
-
-### Cross-Terminal Surplus Aggregation
-
-- `JBSurplus.currentSurplusOf` makes external view calls into each terminal with no gas cap.
-- Aggregated surplus also compounds price-conversion rounding across terminals.
-
-### `addToBalanceOf` Metadata
-
-- `addToBalanceOf` accepts arbitrary metadata.
-- Core ignores that metadata directly, but hooks may interpret it.
-
-### `recordAddedBalanceFor` Access Control
-
-- `JBTerminalStore.recordAddedBalanceFor` has no explicit access control.
-- The balance key includes `msg.sender`, so only a terminal can inflate its own recorded balance.
-- A buggy or malicious terminal can still lie about funds it received.
-
-### Split And Owner-Payout Failure Semantics
-
-- Failed split payouts still consume payout limit.
-- Failed owner payouts also still consume payout limit.
-- Reserved-token split hook reverts can strand tokens at the hook after transfer.
-
-## 8. Accepted Behaviors
-
-### 8.1 Cross-terminal surplus is opt-in shared trust
-
-When a project enables `useTotalSurplusForCashOuts`, it is choosing shared treasury semantics across terminals. That can improve pricing, but it also means each listed terminal is part of the trust boundary.
-
-### 8.2 Failed fee routing is intentionally fail-open
-
-If project `#1` cannot accept a fee payment, core prefers liveness over strict fee collection. For held fees, a failed processing attempt can forgive the fee permanently.
-
-### 8.3 Surplus allowance is keyed by ruleset, not by an abstract cycle
-
-`usedSurplusAllowanceOf` is keyed by `ruleset.id`. If a ruleset auto-rolls without a new ID, allowance usage carries forward.
-
-### 8.4 Fee routing starts fail-open until the wider deployment is wired
-
-Core can be deployed before project `#1` is fully ready. During that period, fee-bearing flows may forgive fees instead of trapping funds.
-
-## 9. Invariants To Verify
-
-- **Balance conservation:** `terminal.balance(token) >= sum(store.balanceOf(projectId, terminal, token))` for projects sharing a terminal.
-- **Fund conservation:** project inflows should cover project outflows plus fees, with rounding favoring the protocol.
-- **Fee monotonicity:** project `#1` should only gain protocol fees through normal mechanics.
-- **Token supply consistency:** protocol credit supply, ERC-20 supply, and pending reserved supply should reconcile.
-- **Payout-limit enforcement:** `usedPayoutLimitOf(...)` must stay `<= payoutLimitOf(...)`.
-- **Surplus-allowance enforcement:** `usedSurplusAllowanceOf(...)` must stay `<= surplusAllowanceOf(...)`.
-- **Cash-out bound:** reclaim plus hook-forwarded amounts must not exceed recorded balance.
-- **Ruleset existence:** after launch, `RULESETS.currentOf(projectId)` should not accidentally go empty.
-- **No flash-loan profit:** `pay()` followed by `cashOutTokensOf()` in one transaction should not be profitable after fees.
-- **Held-fee integrity:** active held-fee entries plus processed fees should equal all fees ever taken under held-fee mode.

package/SKILLS.md

@@ -1,55 +0,0 @@
-# Juicebox Core
-
-## Use This File For
-
-- Use this file when the task touches core protocol behavior: payments, cash outs, terminals, controller actions, rulesets, splits, tokens, permissions, or price feeds.
-- Start here when you know the issue is in core. Then narrow it to one state transition before reading more broadly.
-
-## Read This Next
-
-| If you need... | Open this next |
-|---|---|
-| Repo overview and protocol framing | [`README.md`](./README.md), [`ARCHITECTURE.md`](./ARCHITECTURE.md) |
-| Controller and project lifecycle behavior | [`src/JBController.sol`](./src/JBController.sol), [`src/JBProjects.sol`](./src/JBProjects.sol), [`src/JBTokens.sol`](./src/JBTokens.sol) |
-| Payment, cash-out, surplus, and fee accounting | [`src/JBMultiTerminal.sol`](./src/JBMultiTerminal.sol), [`src/JBTerminalStore.sol`](./src/JBTerminalStore.sol), [`src/JBFundAccessLimits.sol`](./src/JBFundAccessLimits.sol) |
-| Rulesets, permissions, directory, and prices | [`src/JBRulesets.sol`](./src/JBRulesets.sol), [`src/JBPermissions.sol`](./src/JBPermissions.sol), [`src/JBDirectory.sol`](./src/JBDirectory.sol), [`src/JBPrices.sol`](./src/JBPrices.sol) |
-| Shared math, metadata parsing, and constants | [`src/libraries/`](./src/libraries/), [`src/structs/`](./src/structs/), [`src/enums/`](./src/enums/) |
-| Periphery helpers and deployment | [`src/periphery/`](./src/periphery/), [`script/Deploy.s.sol`](./script/Deploy.s.sol), [`script/DeployPeriphery.s.sol`](./script/DeployPeriphery.s.sol) |
-| Payment and cash-out entrypoints | [`references/entrypoints.md`](./references/entrypoints.md) |
-| Packed metadata, errors, events, and hook return shapes | [`references/types-errors-events.md`](./references/types-errors-events.md) |
-| Payment and cash-out behavior in tests | [`test/TestPayBurnRedeemFlow.sol`](./test/TestPayBurnRedeemFlow.sol), [`test/TestCashOut.sol`](./test/TestCashOut.sol), [`test/TestMultiTerminalSurplus.sol`](./test/TestMultiTerminalSurplus.sol), [`test/TestTerminalPreviewParity.sol`](./test/TestTerminalPreviewParity.sol) |
-| Permissions, rulesets, and invariants | [`test/TestPermissions.sol`](./test/TestPermissions.sol), [`test/PermissionEscalation.t.sol`](./test/PermissionEscalation.t.sol), [`test/TestRulesetQueueing.sol`](./test/TestRulesetQueueing.sol), [`test/ComprehensiveInvariant.t.sol`](./test/ComprehensiveInvariant.t.sol), [`test/PermissionsInvariant.t.sol`](./test/PermissionsInvariant.t.sol) |
-| Economic and exploit coverage | [`test/EconomicSimulation.t.sol`](./test/EconomicSimulation.t.sol), [`test/CoreExploitTests.t.sol`](./test/CoreExploitTests.t.sol), [`test/FlashLoanAttacks.t.sol`](./test/FlashLoanAttacks.t.sol), [`test/WeirdTokenTests.t.sol`](./test/WeirdTokenTests.t.sol), [`test/AuditFixes.t.sol`](./test/AuditFixes.t.sol) |
-
-## Repo Map
-
-| Area | Where to look |
-|---|---|
-| Main contracts | [`src/`](./src/) |
-| Libraries, types, and enums | [`src/libraries/`](./src/libraries/), [`src/structs/`](./src/structs/), [`src/interfaces/`](./src/interfaces/), [`src/enums/`](./src/enums/) |
-| Periphery | [`src/periphery/`](./src/periphery/) |
-| Tests | [`test/`](./test/) |
-
-## Purpose
-
-This is the core Juicebox V6 protocol on EVM. It lets projects launch treasury-backed tokens with configurable rulesets for payments, payouts, cash outs, and token issuance.
-
-## Reference Files
-
-| If you need... | Open this next |
-|---|---|
-| Contract map and callable entrypoints | [`references/entrypoints.md`](./references/entrypoints.md) |
-| Types, constants, gotchas, permissions, common errors, events, and hook return shapes | [`references/types-errors-events.md`](./references/types-errors-events.md) |
-
-## Working Rules
-
-- Open the source before relying on any summary here.
-- For runtime bugs, start from the terminal, controller, or store contract that owns the state transition.
-- `JBMultiTerminal` and `JBTerminalStore` should usually be read together.
-- Payment and cash-out previews are part of the protocol surface. Keep them aligned with execution.
-- Payout limits reset by ruleset cycle number. Surplus allowances are keyed by `ruleset.id`. They do not always reset together.
-- Fee handling is subtle. Re-check held fees, fee-free surplus tracking, and feeless-address behavior before changing payout or cash-out logic.
-- Fee-free surplus is a bounded anti-bypass mechanism, not a general exemption bucket.
-- For config or metadata-shape issues, open `references/types-errors-events.md` before changing structs or packed metadata.
-- If previews, accounting, or fee behavior change, verify the other two as well.
-- If a bug looks cross-repo, prove it is not caused by a hook, router, or deployer before patching core.