@bananapus/core-v6 0.0.30 → 0.0.32

package/ADMINISTRATION.md

@@ -2,6 +2,35 @@
 
 Admin privileges and their scope in nana-core-v6.
 
+## At A Glance
+
+| Item | Details |
+|------|---------|
+| Scope | Core Juicebox V6 protocol control plane: projects, permissions, directory, controller, terminals, tokens, prices, splits, and fund access limits. |
+| Operators | Protocol-level contract owners, project owners, delegated operators, controllers, terminals, and ruleset-selected hooks. |
+| Highest-risk actions | Adding immutable price feeds, changing controllers or terminals, deploying or setting a project's ERC-20, and granting broad operator or ROOT permissions. |
+| Recovery posture | Bad immutable choices usually require deploying new infrastructure and migrating project configuration rather than "editing" the existing contracts. |
+
+## Routine Operations
+
+- Whitelist or remove first-controller setters on `JBDirectory` only when rolling out a new controller implementation.
+- Add price feeds only after confirming the exact project scope and pair, because feeds cannot be replaced once written.
+- Manage project operators through `JBPermissions` with the narrowest possible project scope and permission bitmap.
+- Reconfigure controllers, terminals, splits, fund access limits, and rulesets only when the current ruleset flags permit the change.
+- Use protocol-owner functions on `JBFeelessAddresses`, `JBProjects`, and `JBPrices` sparingly because they affect many projects at once.
+
+## One-Way Or High-Risk Actions
+
+- `JBPrices.addPriceFeedFor` is immutable for a given project/currency pair. A bad feed entry cannot be edited in place.
+- `JBController.deployERC20For` and `JBTokens.setTokenFor` are effectively one-time token-binding decisions for a project.
+- The fee beneficiary is hardcoded to project `1` inside `JBMultiTerminal`; changing that requires new terminal deployments.
+- Over-broad ROOT or wildcard permissions can hand an operator more power than intended across a project's full control surface.
+
+## Recovery Notes
+
+- If an immutable contract reference or price feed is wrong, the normal recovery path is redeploying the affected contract layer and migrating projects to the new controller or terminal stack.
+- If a project's controller or terminal setup is wrong but the ruleset still allows migration, recover with `JBDirectory` updates before deploying replacement infrastructure.
+
 ## Roles
 
 ### Project Owner
@@ -90,14 +119,14 @@ Admin privileges and their scope in nana-core-v6.
 |----------|--------------|---------------|-------|-------------|
 | `setControllerOf` | Project owner or operator, OR an `isAllowedToSetFirstController` address (for first controller only) | SET_CONTROLLER (14) | Per project | Sets or migrates a project's controller. Also requires the current ruleset's `allowSetController` flag to be true (unless setting the first controller). Triggers migration lifecycle hooks on both old and new controllers. |
 | `setIsAllowedToSetFirstController` | Contract owner | N/A (onlyOwner) | Protocol-wide | Adds or removes an address from the allowlist of addresses that can set a project's first controller. |
-| `setPrimaryTerminalOf` | Project owner or operator | SET_PRIMARY_TERMINAL (16) | Per project | Sets which terminal is the default for a given token. Adds the terminal to the project if not already present. |
+| `setPrimaryTerminalOf` | Project owner or operator | SET_PRIMARY_TERMINAL (17), plus ADD_TERMINALS (16) if the terminal is not already configured | Per project | Sets which terminal is the default for a given token. Adds the terminal to the project if not already present. |
 | `setTerminalsOf` | Project owner, operator, or the project's controller | SET_TERMINALS (15) | Per project | Replaces the entire list of terminals for a project. If the caller is not the controller, the ruleset must have `allowSetTerminals` enabled. |
 
 ### JBController
 
 | Function | Required Role | Permission ID | Scope | What It Does |
 |----------|--------------|---------------|-------|-------------|
-| `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. |
+| `addPriceFeedFor` | Project owner or operator | ADD_PRICE_FEED (20) | 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. |
@@ -106,9 +135,9 @@ Admin privileges and their scope in nana-core-v6.
 | `mintTokensOf` | Project owner, operator, terminal, or data hook (with mint permission) | MINT_TOKENS (10) | Per project | Mints new tokens. If the caller is not a terminal or data hook, the ruleset must have `allowOwnerMinting` enabled. |
 | `queueRulesetsOf` | Project owner, operator, or OMNICHAIN_RULESET_OPERATOR | QUEUE_RULESETS (2) | Per project | Queues new rulesets at the end of the project's ruleset queue. |
 | `sendReservedTokensToSplitsOf` | Anyone | N/A | Per project | Distributes accumulated reserved tokens to the project's reserved token split group. No permission required -- anyone can trigger this. |
-| `setSplitGroupsOf` | Project owner or operator | SET_SPLIT_GROUPS (18) | Per project | Sets split groups for a project. Must preserve any currently locked splits. |
+| `setSplitGroupsOf` | Project owner or operator | SET_SPLIT_GROUPS (19) | Per project | Sets split groups for a project. Must preserve any currently locked splits. |
 | `setTokenFor` | Project owner or operator | SET_TOKEN (9) | Per project | Assigns an external ERC-20 token to the project. Requires the ruleset's `allowSetCustomToken` flag. Can only be called once (before any token is set). |
-| `setTokenMetadataOf` | Project owner or operator | SET_TOKEN_METADATA (21) | Per project | Sets the name and symbol of a project's ERC-20 token. The project must have a token deployed. |
+| `setTokenMetadataOf` | Project owner or operator | SET_TOKEN_METADATA (22) | Per project | Sets the name and symbol of a project's ERC-20 token. The project must have a token deployed. |
 | `setUriOf` | Project owner or operator | SET_PROJECT_URI (7) | Per project | Updates the project's metadata URI. |
 | `transferCreditsFrom` | Credit holder or operator | TRANSFER_CREDITS (13) | Per project | Transfers internal token credits between addresses. Requires the ruleset's `pauseCreditTransfers` flag to be false. |
 | `migrate` | JBDirectory only | N/A (msg.sender == DIRECTORY) | Per project | Called by the directory during controller migration. Reverts if there are pending reserved tokens. |
@@ -121,11 +150,11 @@ Admin privileges and their scope in nana-core-v6.
 
 | Function | Required Role | Permission ID | Scope | What It Does |
 |----------|--------------|---------------|-------|-------------|
-| `addAccountingContextsFor` | Project owner, operator, or the project's controller | ADD_ACCOUNTING_CONTEXTS (20) | Per project | Adds tokens that the terminal will accept for a project. Requires the ruleset's `allowAddAccountingContext` flag (if a ruleset exists). |
+| `addAccountingContextsFor` | Project owner, operator, or the project's controller | ADD_ACCOUNTING_CONTEXTS (21) | Per project | Adds tokens that the terminal will accept for a project. Requires the ruleset's `allowAddAccountingContext` flag (if a ruleset exists). |
 | `cashOutTokensOf` | Token holder or operator | CASH_OUT_TOKENS (4) | Per project | Cashes out project tokens for a share of the project's surplus. Fees are charged unless the beneficiary is feeless or the cash out tax rate is zero. |
 | `migrateBalanceOf` | Project owner or operator | MIGRATE_TERMINAL (6) | Per project | Migrates a project's balance from this terminal to another. The destination terminal must accept the same token. The ruleset must have `allowTerminalMigration` enabled (checked in JBTerminalStore). The standard 2.5% protocol fee is charged when migrating to a non-feeless terminal. |
 | `sendPayoutsOf` | Anyone (unless `ownerMustSendPayouts` is set) | SEND_PAYOUTS (5) if `ownerMustSendPayouts` | Per project | Sends payouts to the project's payout split group up to the payout limit. Anyone can call unless the ruleset has `ownerMustSendPayouts` enabled, which requires the project owner or an operator with SEND_PAYOUTS permission. |
-| `useAllowanceOf` | Project owner or operator | USE_ALLOWANCE (17) | Per project | Withdraws funds from the project's surplus up to the surplus allowance. Fees are charged unless the owner or beneficiary is feeless. |
+| `useAllowanceOf` | Project owner or operator | USE_ALLOWANCE (18) | Per project | Withdraws funds from the project's surplus up to the surplus allowance. Fees are charged unless the owner or beneficiary is feeless. |
 | `pay` | Anyone | N/A | N/A | Pays a project with tokens. No permission required. |
 | `addToBalanceOf` | Anyone | N/A | N/A | Adds funds to a project's balance without minting tokens. Can optionally return held fees. No permission required. |
 | `processHeldFeesOf` | Anyone | N/A | Per project | Processes held fees that have passed their 28-day unlock period. No permission required. |
@@ -242,12 +271,13 @@ JBPermissions implements a 256-bit packed permission bitmap system:
 | 13 | TRANSFER_CREDITS | `JBController.transferCreditsFrom` |
 | 14 | SET_CONTROLLER | `JBDirectory.setControllerOf` |
 | 15 | SET_TERMINALS | `JBDirectory.setTerminalsOf` |
-| 16 | SET_PRIMARY_TERMINAL | `JBDirectory.setPrimaryTerminalOf` |
-| 17 | USE_ALLOWANCE | `JBMultiTerminal.useAllowanceOf` |
-| 18 | SET_SPLIT_GROUPS | `JBController.setSplitGroupsOf` |
-| 19 | ADD_PRICE_FEED | `JBController.addPriceFeedFor` |
-| 20 | ADD_ACCOUNTING_CONTEXTS | `JBMultiTerminal.addAccountingContextsFor` |
-| 21 | SET_TOKEN_METADATA | `JBController.setTokenMetadataOf` |
+| 16 | ADD_TERMINALS | `JBDirectory.setPrimaryTerminalOf` when it must add a new terminal first |
+| 17 | SET_PRIMARY_TERMINAL | `JBDirectory.setPrimaryTerminalOf` |
+| 18 | USE_ALLOWANCE | `JBMultiTerminal.useAllowanceOf` |
+| 19 | SET_SPLIT_GROUPS | `JBController.setSplitGroupsOf` |
+| 20 | ADD_PRICE_FEED | `JBController.addPriceFeedFor` |
+| 21 | ADD_ACCOUNTING_CONTEXTS | `JBMultiTerminal.addAccountingContextsFor` |
+| 22 | SET_TOKEN_METADATA | `JBController.setTokenMetadataOf` |
 
 ## Immutable Configuration
 
@@ -338,7 +368,7 @@ What admins CANNOT do:
 - **No admin can change the fee beneficiary.** Project ID 1 is hardcoded as the fee recipient. This cannot be changed.
 - **Price feeds cannot be replaced.** Once a price feed is set for a currency pair (in either direction), it is permanent for that project ID. Recovery requires deploying a new JBPrices contract.
 - **Token assignments are one-way.** Once a project's ERC-20 token is set (via `deployERC20For` or `setTokenFor`), it cannot be changed to a different token.
-- **Locked splits cannot be removed.** Splits with a `lockedUntil` timestamp in the future must be preserved (with the same or extended lock) when updating split groups.
+- **Locked splits cannot be removed from the same split table.** Splits with a `lockedUntil` timestamp in the future must be preserved (with the same or extended lock) when updating that split group. This does not automatically freeze successor rulesets; operators that queue new rulesets must consciously carry forward any still-locked economic promises they intend to preserve.
 - **Operators cannot escalate to ROOT via ROOT.** A ROOT operator can set permissions for other operators on the same project but cannot grant ROOT to them or set permissions on the wildcard project ID.
 - **The directory owner cannot set controllers directly.** The directory owner can only manage the `isAllowedToSetFirstController` allowlist. They cannot set or change a project's controller.
 - **Ruleset approval hooks can block changes.** If a ruleset specifies an approval hook, queued rulesets must be approved by that hook before they take effect. A rejected ruleset falls back to the previous approved ruleset's cycling behavior.

package/ARCHITECTURE.md

@@ -1,159 +1,84 @@
-# nana-core-v6 — Architecture
+# Architecture
 
 ## Purpose
 
-Core protocol for Juicebox V6. Provides programmable treasuries with configurable governance, bonding-curve cash outs, split-based payouts, and a compositional hook system.
+`nana-core-v6` is the protocol root. It owns project identity, permissions, rulesets, token supply, treasury balances, payout limits, fee logic, and the hook interfaces that every extension repo composes with.
 
-## Contract Map
+If a change affects accounting, supply, fee behavior, terminal routing, or permission semantics, this is the repo that defines the source of truth.
 
-```
-src/
-├── JBMultiTerminal.sol    — Multi-token payment terminal (pay, cash out, payouts, fees)
-├── JBController.sol       — Orchestrator (project lifecycle, rulesets, token minting, reserved tokens)
-├── JBTerminalStore.sol    — Bookkeeping (balances, payout limits, surplus, bonding curve math)
-├── JBRulesets.sol         — Ruleset lifecycle (linked-list, weight decay, approval hooks)
-├── JBDirectory.sol        — Routes projects to terminals and controllers
-├── JBTokens.sol           — Dual token system (internal credits + ERC-20)
-├── JBSplits.sol           — Packed split storage with lock enforcement
-├── JBFundAccessLimits.sol — Payout limits and surplus allowances
-├── JBPrices.sol           — Price feeds with project-specific + default fallback
-├── JBPermissions.sol      — 256-bit packed permission system
-├── JBProjects.sol         — ERC-721 project ownership
-├── JBERC20.sol            — Cloneable ERC20Votes+Permit token
-├── JBFeelessAddresses.sol — Fee-exempt address registry
-├── JBDeadline.sol         — Approval hook requiring minimum delay
-├── JBChainlinkV3PriceFeed.sol          — Chainlink v3 price feed with staleness + answeredInRound check
-├── JBChainlinkV3SequencerPriceFeed.sol — L2 sequencer-aware price feed (answer != 0 = down)
-├── 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)
-    ├── JBFixedPointNumber.sol      — Decimal adjustment
-    ├── 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
-```
+## Boundaries
 
-## Key Data Flows
+- The core owns balance and supply transitions.
+- Extensions may adjust economics through hooks, but they should not invent competing ledgers.
+- The core deliberately avoids app-specific behaviors like NFT composition, DEX routing strategy, or bridge-specific message transport.
 
-### Payment Flow
+## Main Components
 
-```
-User -> JBMultiTerminal.pay()
-  -> JBTerminalStore.recordPaymentFrom()
-    -> Read current ruleset
-    -> [Optional] Data hook overrides weight
-    -> Calculate token count from weight
-    -> Update balance
-  -> JBController.mintTokensOf()
-    -> Calculate reserved tokens
-    -> Mint beneficiary tokens
-    -> Accumulate pendingReservedTokenBalanceOf
-  -> [Optional] Pay hooks execute
-```
+| Component | Responsibility |
+| --- | --- |
+| `JBMultiTerminal` | Entry point for payments, cash outs, payouts, balance additions, and fee handling |
+| `JBTerminalStore` | Bookkeeping and preview math for payment, payout, allowance, and cash-out paths |
+| `JBController` | Project launch, ruleset queueing, token minting and burning, split-group updates |
+| `JBDirectory` | Maps projects to controllers and terminals |
+| `JBRulesets` | Time-ordered ruleset lifecycle and approval-hook integration |
+| `JBTokens`, `JBERC20`, `JBProjects` | Token and project identity surfaces |
+| `JBSplits`, `JBFundAccessLimits`, `JBPrices`, `JBPermissions` | Shared state for distribution, limits, price conversion, and authorization |
 
-### Cash Out Flow
+## Runtime Model
 
-```
-Holder -> JBMultiTerminal.cashOutTokensOf()
-  -> JBTerminalStore.recordCashOutFor()
-    -> Calculate surplus (all terminals, converted via JBPrices)
-    -> Get totalSupply (including pending reserved)
-    -> [Optional] Data hook overrides parameters
-    -> JBCashOuts.cashOutFrom() — bonding curve
-    -> Deduct balance
-  -> JBController.burnTokensOf()
-  -> Deduct fee from reclaim amount (if applicable), transfer remainder to beneficiary
-  -> [Optional] Cash out hooks execute
-  -> 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)
-```
+### Payment
 
-### Preview Flow
+```text
+terminal receives funds
+  -> terminal store reads the current ruleset and optional data hooks
+  -> store computes weight-based minting results
+  -> controller mints beneficiary tokens and accrues reserved tokens
+  -> pay hooks execute only after settlement
+```
 
-Every core user action has a `view` counterpart that simulates the operation without modifying state. These compose the same internal computation paths as their non-preview counterparts and include data hook effects.
+### Cash Out
 
-```
-Caller -> JBMultiTerminal.previewPayFor(projectId, token, amount, beneficiary, metadata)
-  -> JBTerminalStore.previewPayFrom()
-    -> Read current ruleset, apply data hook
-    -> Calculate token count from weight
-  -> JBController.previewMintOf()
-    -> Split token count into beneficiary + reserved portions
-  -> Returns (ruleset, beneficiaryTokenCount, reservedTokenCount, hookSpecifications)
-
-Caller -> JBMultiTerminal.previewCashOutFrom(holder, projectId, cashOutCount, tokenToReclaim, beneficiary, metadata)
-  -> JBTerminalStore.previewCashOutFrom()
-    -> Calculate surplus, get totalSupply, apply data hook
-    -> JBCashOuts.cashOutFrom() — bonding curve
-  -> Returns (ruleset, reclaimAmount, cashOutTaxRate, hookSpecifications)
-
-Caller -> JBController.previewMintOf(projectId, tokenCount, useReservedPercent)
-  -> Read current ruleset
-  -> Returns (beneficiaryTokenCount, reservedTokenCount)
+```text
+holder requests redemption
+  -> terminal store computes reclaim amount from surplus, supply, and tax settings
+  -> optional data hooks can adjust the calculation inputs
+  -> controller burns tokens
+  -> terminal pays the reclaim amount and routes protocol fees
+  -> cash-out hooks execute only after settlement
 ```
 
-### Payout Flow
+### Payouts And Allowances
 
+```text
+authorized caller
+  -> consumes payout limits or surplus allowances
+  -> funds move to splits, projects, hooks, or direct recipients
 ```
-Owner -> JBMultiTerminal.sendPayoutsOf()
-  -> JBTerminalStore.recordPayoutFor()
-    -> Deduct balance, check payout limits
-  -> Distribute to splits (JBSplits)
-    -> Split to project -> pay project's terminal
-    -> Split to address -> direct transfer
-    -> Split to hook -> IJBSplitHook.processSplitWith()
-  -> Take fees on non-feeless payouts
-```
 
-## Extension Points
+## Critical Invariants
+
+- Preview functions must remain behaviorally aligned with state-changing functions.
+- Data hooks run before settlement and may alter the economics; pay and cash-out hooks run after settlement. That phase boundary is intentional.
+- Reserved tokens and pending reserves affect supply-sensitive math even before distribution.
+- Terminal balances, fee accounting, and surplus calculations must agree. Any drift here contaminates every product repo.
+- Rulesets are time-ordered and approval-aware; deployment wrappers depend on predictable ID progression and activation semantics.
+- Permission checks are not a UI concern. They are part of protocol state transition validity.
 
-| Extension Point | Interface | Called By |
-|----------------|-----------|-----------|
-| Data Hook (pay) | `IJBRulesetDataHook.beforePayRecordedWith` | JBTerminalStore |
-| Data Hook (cashout) | `IJBRulesetDataHook.beforeCashOutRecordedWith` | JBTerminalStore |
-| Pay Hook | `IJBPayHook.afterPayRecordedWith` | JBMultiTerminal |
-| Cash Out Hook | `IJBCashOutHook.afterCashOutRecordedWith` | JBMultiTerminal |
-| Split Hook | `IJBSplitHook.processSplitWith` | JBMultiTerminal, JBController (try-catch; reverts emit `SplitHookReverted`) |
-| Approval Hook | `IJBRulesetApprovalHook.approvalStatusOf` | JBRulesets |
+## Where Complexity Lives
+
+- `JBMultiTerminal`, `JBTerminalStore`, and `JBController` form one accounting pipeline and are easiest to misunderstand when read separately.
+- Preview paths deliberately mirror state-changing paths; keeping them aligned is a permanent maintenance burden.
+- Fee-free surplus, held fees, and payout/allowance interactions create edge cases that are small in code size but large in blast radius.
 
 ## Dependencies
 
-- `@bananapus/permission-ids-v6` — Permission ID constants
-- `@openzeppelin/contracts` — ERC-721, ERC-20, ERC2771, Clones
-- `@prb/math` — Fixed-point math (mulDiv)
-- `@chainlink/contracts` — Price feed interfaces
-- `@uniswap/permit2` — Permit2 token approvals
-
-## Key Constants
-
-- 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)
-- SPLITS_TOTAL_PERCENT = 1,000,000,000
-- NATIVE_TOKEN = 0x000000000000000000000000000000000000EEEe
-- Fee holding: 28 days (2,419,200 seconds)
-- Fee beneficiary: project ID 1
+- `nana-permission-ids-v6` for the shared permission namespace
+- OpenZeppelin, PRBMath, Chainlink, and Permit2 for standards and math utilities
+
+## Safe Change Guide
+
+- Start any nontrivial change by tracing both the preview path and the state-changing path.
+- Read downstream hook repos before changing hook interfaces or metadata expectations.
+- Keep fee logic, balance logic, and surplus logic in sync; "small" tweaks here are almost always ecosystem-wide changes.
+- When adding permissions or changing who is checked against a permission, update ecosystem docs and downstream assumptions immediately.
+- If a change seems local inside core, assume it is not until proven otherwise.