@bananapus/core-v6 0.0.37 → 0.0.39

package/src/libraries/JBPayoutSplitGroupLib.sol

@@ -23,8 +23,11 @@ interface IJBPayoutSplitGroupExecutor {
         returns (uint256 netPayoutAmount);
 }
 
-/// @notice External library for payout split-group distribution extracted to reduce terminal bytecode.
-/// @dev Called via DELEGATECALL from the terminal, so events are emitted from the terminal's address.
+/// @notice Handles distributing payouts to a project's split recipients. Iterates through each split, sends the
+/// proportional amount, and gracefully handles failures — if a split payout reverts (e.g. a hook is broken), the
+/// amount is returned to the project's balance rather than blocking all other splits.
+/// @dev Extracted as an external library to reduce `JBMultiTerminal` bytecode size. Called via DELEGATECALL, so events
+/// are emitted from the terminal's address.
 library JBPayoutSplitGroupLib {
     event PayoutReverted(uint256 indexed projectId, JBSplit split, uint256 amount, bytes reason, address caller);
     event SendPayoutToSplit(
@@ -140,8 +143,8 @@ library JBPayoutSplitGroupLib {
         // slither-disable-next-line reentrancy-events,calls-loop
         try IJBPayoutSplitGroupExecutor(address(this))
             .executePayout({
-                split: split, projectId: projectId, token: token, amount: amount, originalMessageSender: caller
-            }) returns (
+            split: split, projectId: projectId, token: token, amount: amount, originalMessageSender: caller
+        }) returns (
             uint256 payoutAmount
         ) {
             return payoutAmount;

package/src/libraries/JBRulesetMetadataResolver.sol

@@ -4,6 +4,10 @@ pragma solidity 0.8.28;
 import {JBRuleset} from "./../structs/JBRuleset.sol";
 import {JBRulesetMetadata} from "./../structs/JBRulesetMetadata.sol";
 
+/// @notice Unpacks the 256-bit packed `metadata` field from a `JBRuleset` into individual parameters. The metadata
+/// encodes: reservedPercent, cashOutTaxRate, baseCurrency, 14 boolean flags (pausePay, allowOwnerMinting, etc.),
+/// a data hook address, and 14 bits of custom metadata. Used throughout the protocol to read ruleset configuration
+/// without storing each field separately.
 library JBRulesetMetadataResolver {
     function reservedPercent(JBRuleset memory ruleset) internal pure returns (uint16) {
         return uint16(ruleset.metadata >> 4);

package/src/libraries/JBSplitGroupIds.sol

@@ -1,7 +1,8 @@
 // SPDX-License-Identifier: MIT
 pragma solidity 0.8.28;
 
-/// @notice Group IDs that categorize splits.
+/// @notice Well-known split group IDs. The reserved tokens group (ID 1) defines how a project's reserved tokens are
+/// distributed. Payout split groups use the token address cast to `uint256(uint160(token))` as their group ID.
 library JBSplitGroupIds {
     uint256 public constant RESERVED_TOKENS = 1;
 }

package/src/libraries/JBSurplus.sol

@@ -3,7 +3,9 @@ pragma solidity 0.8.28;
 
 import {IJBTerminal} from "../interfaces/IJBTerminal.sol";
 
-/// @notice Surplus calculations.
+/// @notice Calculates a project's total surplus across all its terminals. Surplus is the amount held beyond what's
+/// needed to cover the project's payout limits — it represents the pool available for cash outs and surplus allowance
+/// usage. Aggregates across multiple terminals and tokens, converting to a common currency via `JBPrices`.
 library JBSurplus {
     /// @notice Gets the total current surplus amount across all of a project's terminals.
     /// @dev This amount changes as the value of the balances changes in relation to the currency being used to measure

package/src/periphery/JBMatchingPriceFeed.sol

@@ -1,8 +1,10 @@
 // SPDX-License-Identifier: MIT
 pragma solidity 0.8.28;
 
-import {IJBPriceFeed} from "src/interfaces/IJBPriceFeed.sol";
+import {IJBPriceFeed} from "../interfaces/IJBPriceFeed.sol";
 
+/// @notice A trivial price feed that always returns 1:1 (one unit = one unit). Used when a payout limit is
+/// denominated in the same currency as the terminal's token, so no actual conversion is needed.
 contract JBMatchingPriceFeed is IJBPriceFeed {
     constructor() {}
 

package/src/structs/JBAccountingContext.sol

@@ -1,10 +1,13 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.0;
 
-/// @custom:member token The address of the token that accounting is being done with.
-/// @custom:member decimals The number of decimals expected in that token's fixed point accounting.
-/// @custom:member currency The currency that the token is priced in terms of. By convention, this is
-/// `uint32(uint160(tokenAddress))` for tokens, or a constant ID from e.g. `JBCurrencyIds` for other currencies.
+/// @notice Describes how a terminal accounts for a specific token — its address, decimal precision, and which
+/// currency
+/// it's priced in. Used when recording payments, payouts, and cash outs to ensure correct fixed-point arithmetic.
+/// @custom:member token The token address (use `JBConstants.NATIVE_TOKEN` for ETH).
+/// @custom:member decimals The number of decimals for this token's fixed-point amounts (e.g. 18 for ETH, 6 for USDC).
+/// @custom:member currency The currency ID for price feed lookups. Convention: `uint32(uint160(tokenAddress))` for
+/// tokens, or `JBCurrencyIds.ETH`/`JBCurrencyIds.USD` for well-known currencies.
 struct JBAccountingContext {
     address token;
     uint8 decimals;

package/src/structs/JBFundAccessLimitGroup.sol

@@ -3,23 +3,16 @@ pragma solidity ^0.8.0;
 
 import {JBCurrencyAmount} from "./JBCurrencyAmount.sol";
 
-/// @dev Payout limit example: if the `amount` is 5, the `currency` is 1 (USD), and the terminal's token is ETH, then
-/// the project can pay out 5 USD worth of ETH during a ruleset.
-/// @dev Surplus allowance example: if the `amount` is 5, the `currency` is 1 (USD), and the terminal's token is ETH,
-/// then the project can pay out 5 USD worth of ETH from its surplus during a ruleset. A project's surplus is its
-/// balance minus its current combined payout limit.
-/// @dev If a project has multiple payout limits or surplus allowances, they are all available. They can all be used
-/// during a single ruleset.
-/// @dev The payout limits' and surplus allowances' fixed point amounts have the same number of decimals as the
-/// terminal.
-/// @custom:member terminal The terminal that the payout limits and surplus allowances apply to.
-/// @custom:member token The token that the payout limits and surplus allowances apply to within the `terminal`.
-/// @custom:member payoutLimits An array of payout limits. The payout limits cumulatively dictate the maximum value of
-/// `token`s a project can pay out from its balance in a terminal during a ruleset. Each payout limit can have a unique
-/// currency and amount.
-/// @custom:member surplusAllowances An array of surplus allowances. The surplus allowances cumulatively dictates the
-/// maximum value of `token`s a project can pay out from its surplus (balance less payouts) in a terminal during a
-/// ruleset. Each surplus allowance can have a unique currency and amount.
+/// @notice Defines how much a project can withdraw from a specific terminal and token each funding cycle.
+/// @dev Example — payout limit of 5 USD in an ETH terminal: the project can distribute up to 5 USD worth of ETH to
+/// its splits per cycle. Example — surplus allowance of 5 USD: the project owner can pull up to 5 USD worth of ETH
+/// from the surplus (balance above payout limits).
+/// @dev Multiple limits in different currencies are additive — each can be used independently within one cycle.
+/// @dev Amounts use the same decimal precision as the terminal token (e.g. 18 for ETH, 6 for USDC).
+/// @custom:member terminal The terminal address these limits apply to.
+/// @custom:member token The token address within that terminal these limits apply to.
+/// @custom:member payoutLimits Maximum amounts distributable to splits per cycle, each in a specific currency.
+/// @custom:member surplusAllowances Maximum amounts withdrawable from surplus per cycle, each in a specific currency.
 struct JBFundAccessLimitGroup {
     address terminal;
     address token;

package/src/structs/JBRuleset.sol

@@ -3,32 +3,24 @@ pragma solidity ^0.8.0;
 
 import {IJBRulesetApprovalHook} from "./../interfaces/IJBRulesetApprovalHook.sol";
 
-/// @dev `JBRuleset` timestamps are unix timestamps (seconds since 00:00 January 1st, 1970 UTC).
-/// @custom:member cycleNumber The ruleset's cycle number. Each ruleset's `cycleNumber` is the previous ruleset's
-/// `cycleNumber` plus one. Each project's first ruleset has a `cycleNumber` of 1.
-/// @custom:member id The ruleset's ID, which is a timestamp of when this ruleset's rules were initialized. The
-/// `rulesetId` stays the same for rulesets that automatically cycle over from a manually queued ruleset.
-/// @custom:member basedOnId The `rulesetId` of the ruleset which was active when this ruleset was created.
-/// @custom:member start The timestamp from which this ruleset is considered active.
-/// @custom:member duration The number of seconds the ruleset lasts for. After this duration, a new ruleset will start.
-/// The project owner can queue new rulesets at any time, which will take effect once the current ruleset's duration is
-/// over. If the `duration` is 0, newly queued rulesets will take effect immediately. If a ruleset ends and there are no
-/// new rulesets queued, the current ruleset cycles over to another one with the same properties but a new `start`
-/// timestamp and a `weight` reduced by the ruleset's `weightCutPercent`.
-/// @custom:member weight A fixed point number with 18 decimals which is typically used by payment terminals to
-/// determine how many tokens should be minted when a payment is received. This can be used by other contracts for
-/// arbitrary calculations.
-/// @custom:member weightCutPercent The percentage by which to reduce the `weight` each time a new ruleset starts.
-/// `weight`
-/// is
-/// a percentage out of `JBConstants.MAX_WEIGHT_CUT_PERCENT`. If it's 0, the next ruleset will have the same `weight` by
-/// default. If it's 90%, the next ruleset's `weight` will be 10% smaller. If a ruleset explicitly sets a new `weight`,
-/// the `weightCutPercent` doesn't apply.
-/// @custom:member approvalHook An address of a contract that says whether a queued ruleset should be approved or
-/// rejected. If a
-/// ruleset is rejected, it won't go into effect. An approval hook can be used to create rules which dictate how a
-/// project owner can change their ruleset over time.
-/// @custom:member metadata Extra data associated with a ruleset which can be used by other contracts.
+/// @notice A ruleset defines how a project behaves during a period of time — token issuance rate, cash-out terms,
+/// payout rules, and permissions. Rulesets cycle automatically: when one expires, the next queued (and approved) one
+/// takes effect. If nothing is queued, the current ruleset auto-cycles with decayed weight.
+/// @dev Timestamps are unix timestamps (seconds since epoch).
+/// @custom:member cycleNumber Which cycle this is (starts at 1, increments each cycle).
+/// @custom:member id The ruleset's ID — the unix timestamp when it was first stored. Stays the same across
+/// auto-cycles.
+/// @custom:member basedOnId The ID of the ruleset that was active when this one was created (forms a linked list).
+/// @custom:member start When this ruleset became/becomes active.
+/// @custom:member duration How many seconds the ruleset lasts. 0 = no auto-cycling (must be explicitly replaced).
+/// @custom:member weight Tokens minted per unit paid (18 decimals). The terminal divides payment amount by weight to
+/// determine token issuance. Higher weight = more tokens per unit of payment.
+/// @custom:member weightCutPercent How much to reduce weight each cycle (out of 1,000,000,000). 100,000,000 = 10% cut
+/// per cycle. 0 = no decay. Only applies when a cycle auto-rolls without an explicitly queued replacement.
+/// @custom:member approvalHook A contract that gates whether queued rulesets can take effect (e.g. `JBDeadline` for
+/// minimum notice periods). If the hook rejects a queued ruleset, the current one continues.
+/// @custom:member metadata Packed 256-bit field containing reservedPercent, cashOutTaxRate, baseCurrency, boolean
+/// flags, data hook address, and custom metadata. Decoded by `JBRulesetMetadataResolver`.
 struct JBRuleset {
     uint48 cycleNumber;
     uint48 id;

package/src/structs/JBRulesetConfig.sol

@@ -6,31 +6,19 @@ import {JBFundAccessLimitGroup} from "./JBFundAccessLimitGroup.sol";
 import {JBRulesetMetadata} from "./JBRulesetMetadata.sol";
 import {JBSplitGroup} from "./JBSplitGroup.sol";
 
-/// @custom:member mustStartAtOrAfter The earliest time the ruleset can start.
-/// @custom:member duration The number of seconds the ruleset lasts for, after which a new ruleset will start. A
-/// duration of 0 means that the ruleset will stay active until the project owner explicitly issues a reconfiguration,
-/// at which point a new ruleset will immediately start with the updated properties. If the duration is greater than 0,
-/// a project owner cannot make changes to a ruleset's parameters while it is active – any proposed changes will apply
-/// to the subsequent ruleset. If no changes are proposed, a ruleset rolls over to another one with the same properties
-/// but new `start` timestamp and a cut `weight`.
-/// @custom:member weight A fixed point number with 18 decimals that contracts can use to base arbitrary calculations
-/// on. For example, payment terminals can use this to determine how many tokens should be minted when a payment is
-/// received.
-/// @custom:member weightCutPercent A percent by how much the `weight` of the subsequent ruleset should be reduced, if
-/// the
-/// project owner hasn't queued the subsequent ruleset with an explicit `weight`. If it's 0, each ruleset will have
-/// equal weight. If the number is 90%, the next ruleset will have a 10% smaller weight. This weight is out of
-/// `JBConstants.MAX_WEIGHT_CUT_PERCENT`.
-/// @custom:member approvalHook An address of a contract that says whether a proposed ruleset should be accepted or
-/// rejected. It
-/// can be used to create rules around how a project owner can change ruleset parameters over time.
-/// @custom:member metadata Metadata specifying the controller-specific parameters that a ruleset can have. These
-/// properties cannot change until the next ruleset starts.
-/// @custom:member splitGroups An array of splits to use for any number of groups while the ruleset is active.
-/// @custom:member fundAccessLimitGroups An array of structs which dictate the amount of funds a project can access from
-/// its balance in each payment terminal while the ruleset is active. Amounts are fixed point numbers using the same
-/// number of decimals as the corresponding terminal. The `_payoutLimit` and `_surplusAllowance` parameters must fit in
-/// a `uint232`.
+/// @notice The configuration passed to `JBController.launchRulesetsFor` or `queueRulesetsOf` to define a new ruleset.
+/// Includes the economic parameters (weight, duration, decay), the metadata (permissions and hooks), the split
+/// recipients, and the fund access limits.
+/// @custom:member mustStartAtOrAfter The earliest timestamp the ruleset can begin. Pass 0 to start immediately after
+/// the previous ruleset ends.
+/// @custom:member duration How long the ruleset lasts in seconds. 0 = stays active until explicitly replaced.
+/// @custom:member weight Tokens minted per unit of payment (18 decimals). Pass 1 to inherit decayed weight from the
+/// previous ruleset. Pass 0 for no token issuance.
+/// @custom:member weightCutPercent Decay rate per cycle (out of 1,000,000,000). 100,000,000 = 10% cut. 0 = no decay.
+/// @custom:member approvalHook Contract that must approve the *next* queued ruleset for it to take effect.
+/// @custom:member metadata The ruleset's behavioral flags and parameters (see `JBRulesetMetadata`).
+/// @custom:member splitGroups How payouts and reserved tokens are distributed during this ruleset.
+/// @custom:member fundAccessLimitGroups How much the project can withdraw from each terminal per cycle.
 struct JBRulesetConfig {
     uint48 mustStartAtOrAfter;
     uint32 duration;

package/src/structs/JBRulesetMetadata.sol

@@ -1,38 +1,31 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.0;
 
-/// @custom:member reservedPercent The reserved percent of the ruleset. This number is a percentage calculated out of
-/// `JBConstants.MAX_RESERVED_PERCENT`.
-/// @custom:member cashOutTaxRate The cash out tax rate of the ruleset. This number is a percentage calculated out of
-/// `JBConstants.MAX_CASH_OUT_TAX_RATE`.
-/// @custom:member baseCurrency The currency on which to base the ruleset's weight. By convention, this is
-/// `uint32(uint160(tokenAddress))` for tokens, or a constant ID from e.g. `JBCurrencyIds` for other currencies.
-/// @custom:member pausePay A flag indicating if the pay functionality should be paused during the ruleset.
-/// @custom:member pauseCreditTransfers A flag indicating if the project token transfer functionality should be paused
-/// during the funding cycle.
-/// @custom:member allowOwnerMinting A flag indicating if the project owner or an operator with the `MINT_TOKENS`
-/// permission from the owner should be allowed to mint project tokens on demand during this ruleset.
-/// @custom:member allowTerminalMigration A flag indicating if migrating terminals should be allowed during this
-/// ruleset.
-/// @custom:member allowSetTerminals A flag indicating if a project's terminals can be added or removed.
-/// @custom:member allowSetController A flag indicating if a project's controller can be changed.
-/// @custom:member allowAddAccountingContext A flag indicating if a project can add new accounting contexts for its
-/// terminals to use.
-/// @custom:member allowAddPriceFeed A flag indicating if a project can add new price feeds to calculate exchange rates
-/// between its tokens.
-/// @custom:member ownerMustSendPayouts A flag indicating if privileged payout distribution should be
-/// enforced, otherwise payouts can be distributed by anyone.
-/// @custom:member holdFees A flag indicating if fees should be held during this ruleset.
-/// @custom:member useTotalSurplusForCashOuts A flag indicating if cash outs should use the project's balance held
-/// in all terminals instead of the project's local terminal balance from which the cash out is being fulfilled.
-/// @custom:member useDataHookForPay A flag indicating if the data hook should be used for pay transactions during this
-/// ruleset.
-/// @custom:member useDataHookForCashOut A flag indicating if the data hook should be used for cash out transactions
-/// during
-/// this ruleset.
-/// @custom:member dataHook The data hook to use during this ruleset.
-/// @custom:member metadata Metadata of the metadata, only the 14 least significant bits can be used, the 2 most
-/// significant bits are disregarded.
+/// @notice Human-readable configuration for a ruleset's behavioral flags and parameters. This struct is packed into
+/// 256 bits for on-chain storage (see `JBRulesetMetadataResolver` for the packing layout).
+/// @custom:member reservedPercent Percentage of newly minted tokens set aside for the reserved token split group
+/// (0–10,000 basis points). 5,000 = 50% reserved.
+/// @custom:member cashOutTaxRate Tax applied when holders cash out tokens (0–10,000 basis points). Higher rate = less
+/// reclaim per token. 0 = proportional, 10,000 = no reclaim (100% tax).
+/// @custom:member baseCurrency The currency used to interpret the ruleset's weight for token issuance. Convention:
+/// `uint32(uint160(tokenAddress))` for tokens, or `JBCurrencyIds.ETH`/`JBCurrencyIds.USD` for well-known currencies.
+/// @custom:member pausePay If `true`, the project cannot receive payments during this ruleset.
+/// @custom:member pauseCreditTransfers If `true`, token credit transfers are disabled during this ruleset.
+/// @custom:member allowOwnerMinting If `true`, the project owner (or MINT_TOKENS operator) can mint tokens on demand.
+/// @custom:member allowSetCustomToken If `true`, the project can set a custom ERC-20 token via `setTokenFor`.
+/// @custom:member allowTerminalMigration If `true`, terminals can be migrated to new implementations.
+/// @custom:member allowSetTerminals If `true`, the project's terminal list can be modified.
+/// @custom:member allowSetController If `true`, the project's controller can be changed.
+/// @custom:member allowAddAccountingContext If `true`, new token accounting contexts can be added to terminals.
+/// @custom:member allowAddPriceFeed If `true`, the project can register new price feeds in `JBPrices`.
+/// @custom:member ownerMustSendPayouts If `true`, only the project owner can trigger payout distribution.
+/// @custom:member holdFees If `true`, fees are accumulated but not processed until a future ruleset (or manually).
+/// @custom:member useTotalSurplusForCashOuts If `true`, cash-out calculations use surplus across all terminals (not
+/// just the one being cashed out from).
+/// @custom:member useDataHookForPay If `true`, the data hook is called before recording payments.
+/// @custom:member useDataHookForCashOut If `true`, the data hook is called before recording cash outs.
+/// @custom:member dataHook Contract called before pay/cash-out to potentially override token counts or add hooks.
+/// @custom:member metadata 14 bits of application-specific metadata (upper 2 bits are ignored).
 struct JBRulesetMetadata {
     uint16 reservedPercent;
     uint16 cashOutTaxRate;

package/test/mock/MockMaliciousBeneficiary.sol

@@ -19,12 +19,12 @@ contract MaliciousPayoutBeneficiary is IERC721Receiver, Test {
 
         IJBMultiTerminal(_terminal)
             .sendPayoutsOf({
-                projectId: 2,
-                amount: 5 * 10 ** 18,
-                currency: uint32(uint160(JBConstants.NATIVE_TOKEN)),
-                token: JBConstants.NATIVE_TOKEN,
-                minTokensPaidOut: 0
-            });
+            projectId: 2,
+            amount: 5 * 10 ** 18,
+            currency: uint32(uint160(JBConstants.NATIVE_TOKEN)),
+            token: JBConstants.NATIVE_TOKEN,
+            minTokensPaidOut: 0
+        });
     }
 
     receive() external payable {
@@ -46,15 +46,15 @@ contract MaliciousAllowanceBeneficiary is IERC721Receiver, Test {
 
         IJBMultiTerminal(_terminal)
             .useAllowanceOf({
-                projectId: 2,
-                amount: 5 * 10 ** 18,
-                currency: uint32(uint160(JBConstants.NATIVE_TOKEN)),
-                token: JBConstants.NATIVE_TOKEN,
-                minTokensPaidOut: 0,
-                beneficiary: payable(address(this)),
-                feeBeneficiary: payable(0x000000000000000000000000000000000000007B),
-                memo: "MEMO"
-            });
+            projectId: 2,
+            amount: 5 * 10 ** 18,
+            currency: uint32(uint160(JBConstants.NATIVE_TOKEN)),
+            token: JBConstants.NATIVE_TOKEN,
+            minTokensPaidOut: 0,
+            beneficiary: payable(address(this)),
+            feeBeneficiary: payable(0x000000000000000000000000000000000000007B),
+            memo: "MEMO"
+        });
     }
 
     receive() external payable {

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`