@bananapus/core-v6 0.0.37 → 0.0.39

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.