@bananapus/core-v6 0.0.10 → 0.0.12

package/ADMINISTRATION.md

@@ -0,0 +1,327 @@
+# Administration
+
+Admin privileges and their scope in nana-core-v6.
+
+## Roles
+
+### Project Owner
+
+- **How assigned:** Holds the ERC-721 NFT minted by `JBProjects.createFor()`. Transferable via standard ERC-721 transfer.
+- **Scope:** Controls a single project. The owner's address is `PROJECTS.ownerOf(projectId)`. Operators can be granted subsets of the owner's permissions via `JBPermissions`.
+
+### Controller
+
+- **How assigned:** Set via `JBDirectory.setControllerOf()`. The controller is stored as `controllerOf[projectId]` in JBDirectory. Typically a `JBController` instance.
+- **Scope:** Manages a single project's rulesets, tokens, splits, and fund access limits. Contracts gated by `onlyControllerOf(projectId)` (from `JBControlled`) only accept calls from the address registered as the project's controller in the directory.
+
+### Terminal
+
+- **How assigned:** Set via `JBDirectory.setTerminalsOf()`. Stored in the directory's `_terminalsOf[projectId]` array.
+- **Scope:** Manages fund inflows and outflows for a single project. Terminal identity is verified via `DIRECTORY.isTerminalOf()`. Terminals interact with `JBTerminalStore` using `msg.sender`-scoped bookkeeping -- each terminal can only modify its own balances.
+
+### Operator
+
+- **How assigned:** Granted permissions by any address via `JBPermissions.setPermissionsFor()`. Permissions are stored as a packed `uint256` bitmap per `(operator, account, projectId)` tuple.
+- **Scope:** Can execute specific functions on behalf of the account that granted them permissions, scoped to a specific project ID (or all projects if `projectId = 0` wildcard is used).
+
+### ROOT Permission Holder
+
+- **How assigned:** Granted the ROOT permission (ID 1) by an account via `JBPermissions`. ROOT on a specific project grants all permissions for that project. ROOT cannot be granted on the wildcard project ID (0) to prevent unlimited cross-project access.
+- **Scope:** ROOT holders for a project can do anything the project owner can do for that project. ROOT holders can also grant non-ROOT permissions to other operators for the same project but cannot grant ROOT to others or set wildcard permissions.
+
+### Directory Owner
+
+- **How assigned:** Set at JBDirectory deployment via the Ownable constructor. Transferable via `Ownable.transferOwnership()`.
+- **Scope:** Protocol-wide. Controls which addresses are allowed to set a project's first controller (`isAllowedToSetFirstController`).
+
+### JBProjects Owner
+
+- **How assigned:** Set at JBProjects deployment via the Ownable constructor. Transferable via `Ownable.transferOwnership()`.
+- **Scope:** Protocol-wide. Can set the `tokenUriResolver` that resolves project NFT metadata URIs.
+
+### JBPrices Owner
+
+- **How assigned:** Set at JBPrices deployment via the Ownable constructor. Transferable via `Ownable.transferOwnership()`.
+- **Scope:** Protocol-wide. Can add default price feeds (project ID 0) that apply to all projects as fallback.
+
+### JBFeelessAddresses Owner
+
+- **How assigned:** Set at JBFeelessAddresses deployment via the Ownable constructor. Transferable via `Ownable.transferOwnership()`.
+- **Scope:** Protocol-wide. Controls which addresses are exempt from protocol fees.
+
+### JBERC20 Owner
+
+- **How assigned:** Set to the `JBTokens` contract address when a project's ERC-20 is deployed or initialized.
+- **Scope:** Single token contract. Only the owner (JBTokens) can mint and burn tokens.
+
+### Omnichain Ruleset Operator
+
+- **How assigned:** Immutable address set in the `JBController` constructor as `OMNICHAIN_RULESET_OPERATOR`.
+- **Scope:** Can call `launchRulesetsFor` and `queueRulesetsOf` on any project, bypassing owner permission checks. This allows the omnichain deployer to synchronize rulesets across chains.
+
+### Data Hook
+
+- **How assigned:** Specified in a ruleset's metadata as the `dataHook` address. Active only during the ruleset it is configured for.
+- **Scope:** Can mint tokens via `JBController.mintTokensOf()` when the data hook reports `hasMintPermissionFor()` returns true. Also controls pay/cashout hook specifications returned from `JBTerminalStore`.
+
+### Fee Beneficiary (Project ID 1)
+
+- **How assigned:** Hardcoded as `_FEE_BENEFICIARY_PROJECT_ID = 1` in JBMultiTerminal.
+- **Scope:** Receives all protocol fees (2.5%) from payouts, surplus allowance usage, and cash outs with non-zero tax rates. This is the first project created during deployment.
+
+## Privileged Functions
+
+### JBPermissions
+
+| Function | Required Role | Permission ID | Scope | What It Does |
+|----------|--------------|---------------|-------|-------------|
+| `setPermissionsFor` | Account owner, or ROOT operator for that account+project | ROOT (1) | Per account + project | Sets the permission bitmap for an operator. ROOT operators can set non-ROOT permissions for the same project but cannot grant ROOT or set wildcard project permissions. |
+
+### JBProjects
+
+| Function | Required Role | Permission ID | Scope | What It Does |
+|----------|--------------|---------------|-------|-------------|
+| `setTokenUriResolver` | Contract owner | N/A (onlyOwner) | Protocol-wide | Sets the contract that resolves token URIs for all project NFTs. |
+| `createFor` | Anyone | N/A | N/A | Creates a new project NFT. No permission required -- anyone can create a project for any owner. |
+
+### JBDirectory
+
+| Function | Required Role | Permission ID | Scope | What It Does |
+|----------|--------------|---------------|-------|-------------|
+| `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. |
+| `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 |
+|----------|--------------|---------------|-------|-------------|
+| `addPriceFeed` | Project owner or operator | ADD_PRICE_FEED (19) | Per project | Adds a price feed for a project. Requires the ruleset's `allowAddPriceFeed` flag. Price feeds are immutable once set. |
+| `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. |
+| `launchProjectFor` | Anyone | N/A | N/A | Creates a new project, sets this controller, configures terminals, and queues initial rulesets. No permission required. |
+| `launchRulesetsFor` | Project owner, operator, or OMNICHAIN_RULESET_OPERATOR | LAUNCH_RULESETS (3) + SET_TERMINALS (15) | Per project | Queues initial rulesets and configures terminals for an existing project that has no rulesets yet. Also sets this contract as the project's controller. |
+| `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. |
+| `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). |
+| `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. |
+| `beforeReceiveMigrationFrom` | JBDirectory only | N/A (msg.sender == DIRECTORY) | Per project | Called before migration to prepare the new controller. Copies metadata URI and distributes pending reserved tokens from the old controller. |
+| `afterReceiveMigrationFrom` | JBDirectory only | N/A (msg.sender == DIRECTORY) | Per project | Called after migration completes. Currently a no-op. |
+| `executePayReservedTokenToTerminal` | Self only | N/A (msg.sender == address(this)) | Internal | Pays a terminal with reserved tokens. Called internally via try-catch during reserved token distribution. |
+
+### JBMultiTerminal
+
+| 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). |
+| `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). |
+| `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. |
+| `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. |
+| `executePayout` | Self only | N/A (msg.sender == address(this)) | Internal | Executes a single payout to a split. Called internally via try-catch during payout distribution. |
+| `executeProcessFee` | Self only | N/A (msg.sender == address(this)) | Internal | Processes a fee payment to the fee beneficiary project. Called internally via try-catch. |
+| `executeTransferTo` | Self only | N/A (msg.sender == address(this)) | Internal | Transfers tokens to an address. Called internally via try-catch during payout leftover distribution. |
+
+### JBTokens
+
+| Function | Required Role | Permission ID | Scope | What It Does |
+|----------|--------------|---------------|-------|-------------|
+| `burnFrom` | Project's controller | N/A (onlyControllerOf) | Per project | Burns tokens and/or credits from a holder. Credits are burned first, then ERC-20 tokens. |
+| `claimTokensFor` | Project's controller | N/A (onlyControllerOf) | Per project | Converts credits to ERC-20 tokens for a holder. |
+| `deployERC20For` | Project's controller | N/A (onlyControllerOf) | Per project | Deploys a cloned JBERC20 token for the project. |
+| `mintFor` | Project's controller | N/A (onlyControllerOf) | Per project | Mints new tokens (ERC-20 if deployed) or credits for a holder. |
+| `setTokenFor` | Project's controller | N/A (onlyControllerOf) | Per project | Sets an external ERC-20 token for the project. Cannot be changed once set. |
+| `transferCreditsFrom` | Project's controller | N/A (onlyControllerOf) | Per project | Transfers credits between addresses. |
+
+### JBSplits
+
+| Function | Required Role | Permission ID | Scope | What It Does |
+|----------|--------------|---------------|-------|-------------|
+| `setSplitGroupsOf` | Project's controller, OR the address whose first 160 bits match the group ID (for self-namespaced splits) | N/A (onlyControllerOf or msg.sender namespace) | Per project | Sets split groups for a project/ruleset. Must preserve any currently locked splits. Percentage total per group must not exceed 100%. |
+
+### JBFundAccessLimits
+
+| Function | Required Role | Permission ID | Scope | What It Does |
+|----------|--------------|---------------|-------|-------------|
+| `setFundAccessLimitsFor` | Project's controller | N/A (onlyControllerOf) | Per project | Sets payout limits and surplus allowances for a project's ruleset. Limits must be in strictly increasing currency order. |
+
+### JBRulesets
+
+| Function | Required Role | Permission ID | Scope | What It Does |
+|----------|--------------|---------------|-------|-------------|
+| `queueFor` | Project's controller | N/A (onlyControllerOf) | Per project | Queues a new ruleset with specified duration, weight, weight cut percent, approval hook, and metadata. |
+| `updateRulesetWeightCache` | Anyone | N/A | Per project | Updates the cached weight for a ruleset to avoid excessive iteration. No permission required -- anyone can call this maintenance function. |
+
+### JBPrices
+
+| Function | Required Role | Permission ID | Scope | What It Does |
+|----------|--------------|---------------|-------|-------------|
+| `addPriceFeedFor` | Contract owner (for project ID 0 defaults) or project's controller (for project-specific feeds) | N/A (onlyOwner or onlyControllerOf) | Protocol-wide or per project | Adds an immutable price feed for a currency pair. Default feeds (project 0) apply as fallback for all projects. |
+
+### JBFeelessAddresses
+
+| Function | Required Role | Permission ID | Scope | What It Does |
+|----------|--------------|---------------|-------|-------------|
+| `setFeelessAddress` | Contract owner | N/A (onlyOwner) | Protocol-wide | Marks an address as feeless or not. Feeless addresses do not incur the 2.5% protocol fee on payouts, surplus allowance usage, or cash outs. |
+
+### JBERC20
+
+| Function | Required Role | Permission ID | Scope | What It Does |
+|----------|--------------|---------------|-------|-------------|
+| `mint` | Contract owner (JBTokens) | N/A (onlyOwner) | Per token | Mints new tokens to an address. |
+| `burn` | Contract owner (JBTokens) | N/A (onlyOwner) | Per token | Burns tokens from an address. |
+| `initialize` | Anyone (once) | N/A | Per token | Initializes the token name, symbol, and owner. Can only be called once. |
+
+### JBTerminalStore
+
+JBTerminalStore has no explicit access control modifiers. Instead, it uses `msg.sender`-scoped storage -- each terminal can only read and write its own balance slots. The functions are designed to be called by terminal contracts:
+
+| Function | Implicit Caller | What It Does |
+|----------|----------------|-------------|
+| `recordAddedBalanceFor` | Any address (terminal) | Increments the caller's recorded balance for a project/token. |
+| `recordCashOutFor` | Any address (terminal) | Records a cash out, calculating reclaim amounts via bonding curve. Decrements the caller's balance. |
+| `recordPaymentFrom` | Any address (terminal) | Records a payment, calculating token issuance via weight. Increments the caller's balance. |
+| `recordPayoutFor` | Any address (terminal) | Records a payout against payout limits. Decrements the caller's balance. |
+| `recordTerminalMigration` | Any address (terminal) | Records a full balance migration. Requires the ruleset's `allowTerminalMigration` flag. Zeros out the caller's balance. |
+| `recordUsedAllowanceOf` | Any address (terminal) | Records surplus allowance usage. Decrements the caller's balance. |
+
+## Permission System
+
+JBPermissions implements a 256-bit packed permission bitmap system:
+
+- **256 permission slots**: Each bit in a `uint256` represents one permission. Bit 0 is reserved (cannot be set). Bits 1-255 are available for permission IDs.
+- **ROOT permission (ID 1)**: Acts as a superuser for the granted project. A ROOT operator passes all permission checks for that project via `includeRoot: true`.
+- **Wildcard project ID (0)**: Granting a permission on project ID 0 makes it apply to all projects for that account. ROOT cannot be granted on the wildcard project ID to prevent unlimited cross-project access.
+- **Operator delegation**: Any address can grant any other address specific permissions. The `_requirePermissionFrom` check passes if `msg.sender == account` OR if the sender has the required permission (with ROOT fallback and wildcard fallback).
+- **Override pattern**: `_requirePermissionAllowingOverrideFrom` adds an `alsoGrantAccessIf` boolean that bypasses the permission check entirely when true. This is used to allow terminals, controllers, and data hooks to call privileged functions without explicit operator permissions.
+
+### Permission IDs Used in nana-core-v6
+
+| ID | Name | Function It Gates |
+|----|------|-------------------|
+| 1 | ROOT | All permissions. Also allows setting non-ROOT permissions for others on the same project. |
+| 2 | QUEUE_RULESETS | `JBController.queueRulesetsOf` |
+| 3 | LAUNCH_RULESETS | `JBController.launchRulesetsFor` |
+| 4 | CASH_OUT_TOKENS | `JBMultiTerminal.cashOutTokensOf` |
+| 5 | SEND_PAYOUTS | `JBMultiTerminal.sendPayoutsOf` (only when `ownerMustSendPayouts` is set) |
+| 6 | MIGRATE_TERMINAL | `JBMultiTerminal.migrateBalanceOf` |
+| 7 | SET_PROJECT_URI | `JBController.setUriOf` |
+| 8 | DEPLOY_ERC20 | `JBController.deployERC20For` |
+| 9 | SET_TOKEN | `JBController.setTokenFor` |
+| 10 | MINT_TOKENS | `JBController.mintTokensOf` |
+| 11 | BURN_TOKENS | `JBController.burnTokensOf` |
+| 12 | CLAIM_TOKENS | `JBController.claimTokensFor` |
+| 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.addPriceFeed` |
+| 20 | ADD_ACCOUNTING_CONTEXTS | `JBMultiTerminal.addAccountingContextsFor` |
+
+## Immutable Configuration
+
+The following values are set at deploy time and cannot be changed:
+
+### JBController
+- `DIRECTORY` -- the directory contract
+- `FUND_ACCESS_LIMITS` -- the fund access limits contract
+- `PERMISSIONS` -- the permissions contract (from JBPermissioned)
+- `PRICES` -- the prices contract
+- `PROJECTS` -- the projects NFT contract
+- `RULESETS` -- the rulesets contract
+- `SPLITS` -- the splits contract
+- `TOKENS` -- the tokens contract
+- `OMNICHAIN_RULESET_OPERATOR` -- the address allowed to launch/queue rulesets for any project
+
+### JBMultiTerminal
+- `DIRECTORY` -- derived from STORE.DIRECTORY()
+- `FEELESS_ADDRESSES` -- the feeless addresses registry
+- `FEE` -- hardcoded at 25 (2.5% of MAX_FEE=1000)
+- `PERMISSIONS` -- the permissions contract
+- `PERMIT2` -- the Uniswap Permit2 contract
+- `PROJECTS` -- the projects NFT contract
+- `RULESETS` -- derived from STORE.RULESETS()
+- `SPLITS` -- the splits contract
+- `STORE` -- the terminal store contract
+- `TOKENS` -- the tokens contract
+- `_FEE_BENEFICIARY_PROJECT_ID` -- hardcoded as 1
+- `_FEE_HOLDING_SECONDS` -- hardcoded as 2,419,200 (28 days)
+
+### JBDirectory
+- `PERMISSIONS` -- the permissions contract
+- `PROJECTS` -- the projects NFT contract
+
+### JBPrices
+- `DIRECTORY` -- the directory contract
+- `PERMISSIONS` -- the permissions contract
+- `PROJECTS` -- the projects NFT contract
+- Price feeds are immutable once set (cannot be replaced or removed)
+
+### JBTokens
+- `DIRECTORY` -- the directory contract
+- `TOKEN` -- the JBERC20 implementation used for cloning
+- Project token assignments are immutable once set (cannot be changed to a different token)
+
+### JBRulesets
+- `DIRECTORY` -- the directory contract
+
+### JBSplits
+- `DIRECTORY` -- the directory contract
+
+### JBFundAccessLimits
+- `DIRECTORY` -- the directory contract
+
+### JBTerminalStore
+- `DIRECTORY` -- the directory contract
+- `PRICES` -- the prices contract
+- `RULESETS` -- the rulesets contract
+
+### JBPermissions
+- Trusted forwarder for ERC-2771 meta-transactions
+
+## Ruleset Flags That Gate Admin Actions
+
+Several admin functions are further gated by boolean flags in the active ruleset's metadata. These flags are set when the ruleset is queued and cannot be changed until a new ruleset takes effect:
+
+| Flag | What It Gates |
+|------|--------------|
+| `allowOwnerMinting` | Whether the project owner/operator can call `mintTokensOf`. Terminals and data hooks can always mint regardless. |
+| `allowSetCustomToken` | Whether `setTokenFor` can be called. |
+| `allowTerminalMigration` | Whether `migrateBalanceOf` / `recordTerminalMigration` can proceed. |
+| `allowSetTerminals` | Whether `setTerminalsOf` can be called by non-controller callers. |
+| `allowSetController` | Whether `setControllerOf` can be called (checked via `IJBDirectoryAccessControl`). |
+| `allowAddAccountingContext` | Whether `addAccountingContextsFor` can add new token contexts. |
+| `allowAddPriceFeed` | Whether `addPriceFeed` can add new price feeds. |
+| `ownerMustSendPayouts` | Whether `sendPayoutsOf` requires SEND_PAYOUTS permission (otherwise anyone can call it). |
+| `pausePay` | Whether payments are paused (checked in JBTerminalStore). |
+| `pauseCreditTransfers` | Whether credit transfers are paused. |
+| `holdFees` | Whether fees are held (deferred for 28 days) instead of being processed immediately. |
+
+## Admin Boundaries
+
+What admins CANNOT do:
+
+- **Project owners cannot access other projects' funds.** All permission checks are scoped to a specific `projectId`. A project owner's permissions only apply to their own project.
+- **Controllers cannot bypass terminal accounting.** JBTerminalStore uses `msg.sender`-scoped balances. A controller cannot directly manipulate a terminal's recorded balances -- only the terminal itself can update its own balance slots.
+- **Terminals cannot mint tokens without controller involvement.** Token minting goes through the controller's `mintTokensOf`, which enforces ruleset rules (reserved percent, `allowOwnerMinting`).
+- **No single admin can change the fee rate.** The fee (2.5%) is hardcoded as a constant in JBMultiTerminal. Changing it requires deploying a new terminal contract.
+- **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.
+- **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.
+- **Reserved tokens must be distributed before controller migration.** The `migrate` function reverts if `pendingReservedTokenBalanceOf[projectId] > 0`, preventing loss of reserved tokens during migration.
+- **The JBTerminalStore has no admin functions.** It has no owner, no permission checks, and no special roles. Access is controlled entirely by the msg.sender-scoped storage pattern -- callers can only affect their own balance slots.

package/ARCHITECTURE.md

@@ -0,0 +1,115 @@
+# nana-core-v6 — 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.
+
+## Contract Map
+
+```
+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 check
+├── JBChainlinkV3SequencerPriceFeed.sol — L2 sequencer-aware price feed
+├── abstract/
+│   ├── JBPermissioned.sol — Base for permission-checked contracts
+│   └── JBControlled.sol   — Base for controller-gated contracts
+└── libraries/
+    ├── JBCashOuts.sol              — Bonding curve math
+    ├── JBFees.sol                  — Fee calculation (forward/backward)
+    ├── JBRulesetMetadataResolver.sol — Bit-packed metadata (256 bits)
+    ├── JBMetadataResolver.sol      — Variable-length key-value metadata
+    ├── JBFixedPointNumber.sol      — Decimal adjustment
+    ├── JBConstants.sol             — Protocol constants
+    └── JBSplitGroupIds.sol         — Split group ID constants
+```
+
+## Key Data Flows
+
+### Payment Flow
+
+```
+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
+```
+
+### Cash Out Flow
+
+```
+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()
+  -> Transfer reclaimed tokens to beneficiary
+  -> [Optional] Cash out hooks execute
+  -> Take fees (2.5% to project #1)
+```
+
+### Payout Flow
+
+```
+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
+
+| 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 |
+| Approval Hook | `IJBRulesetApprovalHook.approvalStatusOf` | JBRulesets |
+
+## 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%), MAX_FEE = 1000
+- 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

package/RISKS.md

@@ -0,0 +1,68 @@
+# nana-core-v6 — Risks
+
+## Trust Assumptions
+
+### What You Trust
+
+1. **Shared Infrastructure** — All projects share the same JBMultiTerminal and JBController instances. A bug in these contracts affects every project.
+2. **Project Owner** — The ERC-721 holder can queue new rulesets, set terminals, configure splits, and delegate permissions. A malicious or compromised owner can fundamentally change project economics.
+3. **Data Hooks** — If a ruleset specifies a data hook, that hook has absolute control over token minting weights and cash out parameters. A malicious data hook can drain the entire project treasury.
+4. **Approval Hooks** — Can approve or reject ruleset transitions. A reverting approval hook doesn't freeze the project (try-catch fallback), but a malicious one could allow unexpected transitions.
+5. **Price Feeds** — Surplus calculations depend on Chainlink price feeds. Stale or manipulated feeds affect cash out values and payout calculations. Staleness causes reverts (DoS), not fund loss.
+6. **Fee Project (#1)** — 2.5% fees go to project #1. If project #1's terminal is misconfigured, fees are returned to the originating project's balance (not lost).
+
+### What You Do NOT Need to Trust
+
+- **Other projects** — Each project's balance is isolated by terminal address in JBTerminalStore
+- **Token holders** — Can only cash out proportional to the bonding curve
+- **Permit2** — Optional; projects work without it
+
+## Known Risks
+
+### By Design
+
+| Risk | Description | Mitigation |
+|------|-------------|------------|
+| Data hook omnipotence | Data hooks override bonding curve parameters | Only use audited, trusted data hooks |
+| Last-holder advantage | Last token holder redeems remaining surplus at 1:1 | Bonding curve math; inherent to the design |
+| Pending reserved inflation | Pending reserved tokens dilute cash out values | Call `sendReservedTokensToSplitsOf` regularly |
+| No reentrancy guard | Protocol relies on CEI ordering, not mutex | State updates before all external calls |
+| Weight cache requirement | Projects with >20k cycles need progressive cache updates | Anyone can call `updateRulesetWeightCache` |
+
+### Operational
+
+| Risk | Description | Mitigation |
+|------|-------------|------------|
+| Price feed DoS | Stale/reverting price feed blocks multi-currency operations | Monitor feed health; single-currency projects unaffected |
+| Split gas exhaustion | Very large split arrays (100+) may exceed block gas | Keep split count reasonable (<50) |
+| Held fee growth | Held fees array grows without cleanup | `_nextHeldFeeIndexOf` pointer skips processed entries |
+
+## Reentrancy Analysis
+
+No `ReentrancyGuard`. Relies on state ordering (checks-effects-interactions):
+
+| Function | State Updated Before External Call | Risk |
+|----------|-----------------------------------|------|
+| `_cashOutTokensOf` | Store balance deducted, tokens burned BEFORE transfer | LOW |
+| `_pay` | Store balance added, tokens minted BEFORE pay hooks | LOW |
+| `executePayout` | Payout limit recorded BEFORE split hook calls | LOW |
+| `processHeldFeesOf` | Index updated BEFORE fee processing | LOW |
+| `_sendReservedTokensToSplitsOf` | Pending balance zeroed BEFORE minting | LOW |
+
+**Key defense:** `JBTerminalStore_InadequateTerminalStoreBalance` revert prevents extracting more than available balance regardless of reentrancy.
+
+## Permission Security
+
+- ROOT (ID 1) grants all permissions but cannot be set for wildcard `projectId = 0`
+- ROOT operators cannot grant ROOT to other addresses
+- Permission 0 is reserved and cannot be set
+- All permission checks support ERC-2771 meta-transactions
+
+## Proven Invariants
+
+1. No flash-loan profit (12 attack vectors tested)
+2. Terminal balance >= sum of recorded project balances
+3. Total inflows >= total outflows
+4. Fee project balance monotonically increases
+5. Token supply = creditSupply + erc20.totalSupply()
+6. Current ruleset always exists after launch

package/SKILLS.md

@@ -246,6 +246,11 @@ The core Juicebox V6 protocol on EVM: a modular system for launching treasury-ba
 - `IJBDirectoryAccessControl` has `setControllerAllowed()` and `setTerminalsAllowed()` -- NOT `setControllerAllowedFor()`
 - Price feeds are immutable once set in `JBPrices` -- they cannot be replaced or removed
 - `JBFundAccessLimits` requires payout limits and surplus allowances to be in strictly increasing currency order to prevent duplicates
+- **Empty `fundAccessLimitGroups` = zero payouts, NOT unlimited.** If a ruleset's `fundAccessLimitGroups` array is empty (or has no entry for the terminal/token), `payoutLimitsOf()` returns an empty array → cumulative limit is 0 → `sendPayoutsOf()` reverts on any amount. To allow unlimited payouts, explicitly set a payout limit with `amount: type(uint224).max`.
+- **`groupId` (uint256) vs `currency` (uint32) are different types for the same address.** `JBSplitGroup.groupId` is `uint256(uint160(tokenAddress))` while `JBAccountingContext.currency` is `uint32(uint160(tokenAddress))`. These truncate differently — only `NATIVE_TOKEN` (0x000000000000000000000000000000000000EEEe) matches by coincidence. Don't confuse them.
+- **`JBAccountingContext.currency` is NOT `baseCurrency` — by design.** `baseCurrency` in ruleset metadata uses abstract real-world values (1 = ETH, 2 = USD) so rulesets are portable across chains — `baseCurrency=2` means "issue X tokens per USD" whether on Ethereum, Base, or Arbitrum. `JBAccountingContext.currency` uses token-derived values (`uint32(uint160(tokenAddress))`) because terminals track specific tokens at specific addresses — e.g. NATIVE_TOKEN = 61166, USDC on Ethereum = 909516616, USDC on Base = 3169378579. `JBPrices` mediates between the two: it converts token-derived currencies to/from abstract currencies (e.g. USDC token → USD concept, NATIVE_TOKEN → ETH concept) so that payout limits denominated in USD work correctly regardless of which token the terminal holds. The separation is what makes cross-chain consistency possible: same ruleset, different terminal accounting per chain.
+- **Don't queue multiple identical rulesets.** A ruleset with a `duration` automatically cycles — no need to queue copies. Queue multiple rulesets only when configuration actually changes between periods (e.g. different weight, splits, or limits).
+- **`NATIVE_TOKEN` represents a different token on each chain.** `NATIVE_TOKEN` (`0x000000000000000000000000000000000000EEEe`) is the token received via `msg.value` — ETH on Ethereum/Base/Optimism/Arbitrum, CELO on Celo, etc. Its currency is `uint32(uint160(NATIVE_TOKEN))` = 61166. A `JBMatchingPriceFeed` (returns 1:1) is deployed for `ETH:NATIVE_TOKEN` on ETH-native chains so that `baseCurrency=ETH` resolves correctly to the native token. On non-ETH-native chains, a different price feed would be needed.
 
 ## Example Integration
 

package/STYLE_GUIDE.md

@@ -0,0 +1,465 @@
+# Style Guide
+
+How we write Solidity and organize repos across the Juicebox V6 ecosystem. `nana-core-v6` is the gold standard — when in doubt, match what it does.
+
+## File Organization
+
+```
+src/
+├── Contract.sol              # Main contracts in root
+├── abstract/                 # Base contracts (JBPermissioned, JBControlled)
+├── enums/                    # One enum per file
+├── interfaces/               # One interface per file, prefixed with I
+├── libraries/                # Pure/view logic, prefixed with JB
+├── periphery/                # Utility contracts (deadlines, price feeds)
+└── structs/                  # One struct per file, prefixed with JB
+```
+
+One contract/interface/struct/enum per file. Name the file after the type it contains.
+
+**Structs, enums, libraries, and interfaces always go in their subdirectories** (`src/structs/`, `src/enums/`, `src/libraries/`, `src/interfaces/`) — never inline in contract files or placed in `src/` root. This keeps type definitions discoverable and import paths consistent across repos.
+
+## Pragma Versions
+
+```solidity
+// Contracts — pin to exact version
+pragma solidity 0.8.26;
+
+// Interfaces, structs, enums — caret for forward compatibility
+pragma solidity ^0.8.0;
+
+// Libraries — caret, may use newer features
+pragma solidity ^0.8.17;
+```
+
+## Imports
+
+Named imports only. Grouped by source, alphabetized within each group:
+
+```solidity
+// External packages (alphabetized)
+import {ERC2771Context} from "@openzeppelin/contracts/metatx/ERC2771Context.sol";
+import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
+import {SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
+import {mulDiv} from "@prb/math/src/Common.sol";
+
+// Local: abstract contracts
+import {JBPermissioned} from "./abstract/JBPermissioned.sol";
+
+// Local: interfaces (alphabetized)
+import {IJBController} from "./interfaces/IJBController.sol";
+import {IJBDirectory} from "./interfaces/IJBDirectory.sol";
+import {IJBMultiTerminal} from "./interfaces/IJBMultiTerminal.sol";
+
+// Local: libraries (alphabetized)
+import {JBConstants} from "./libraries/JBConstants.sol";
+import {JBFees} from "./libraries/JBFees.sol";
+
+// Local: structs (alphabetized)
+import {JBAccountingContext} from "./structs/JBAccountingContext.sol";
+import {JBSplit} from "./structs/JBSplit.sol";
+```
+
+## Contract Structure
+
+Section banners divide the contract into a fixed ordering. Every contract with 50+ lines uses these banners:
+
+```solidity
+/// @notice One-line description.
+contract JBExample is JBPermissioned, IJBExample {
+    // A library that does X.
+    using SomeLib for SomeType;
+
+    //*********************************************************************//
+    // --------------------------- custom errors ------------------------- //
+    //*********************************************************************//
+
+    error JBExample_SomethingFailed(uint256 amount);
+
+    //*********************************************************************//
+    // ------------------------- public constants ------------------------ //
+    //*********************************************************************//
+
+    uint256 public constant override FEE = 25;
+
+    //*********************************************************************//
+    // ----------------------- internal constants ------------------------ //
+    //*********************************************************************//
+
+    uint256 internal constant _FEE_BENEFICIARY_PROJECT_ID = 1;
+
+    //*********************************************************************//
+    // --------------- public immutable stored properties ---------------- //
+    //*********************************************************************//
+
+    IJBDirectory public immutable override DIRECTORY;
+
+    //*********************************************************************//
+    // --------------------- public stored properties -------------------- //
+    //*********************************************************************//
+
+    //*********************************************************************//
+    // -------------------- internal stored properties ------------------- //
+    //*********************************************************************//
+
+    //*********************************************************************//
+    // -------------------------- constructor ---------------------------- //
+    //*********************************************************************//
+
+    //*********************************************************************//
+    // ---------------------- receive / fallback ------------------------- //
+    //*********************************************************************//
+
+    //*********************************************************************//
+    // --------------------------- modifiers ----------------------------- //
+    //*********************************************************************//
+
+    //*********************************************************************//
+    // ---------------------- external transactions ---------------------- //
+    //*********************************************************************//
+
+    //*********************************************************************//
+    // ----------------------- external views ---------------------------- //
+    //*********************************************************************//
+
+    //*********************************************************************//
+    // ----------------------- public transactions ----------------------- //
+    //*********************************************************************//
+
+    //*********************************************************************//
+    // ----------------------- internal helpers -------------------------- //
+    //*********************************************************************//
+
+    //*********************************************************************//
+    // ----------------------- internal views ---------------------------- //
+    //*********************************************************************//
+
+    //*********************************************************************//
+    // ----------------------- private helpers --------------------------- //
+    //*********************************************************************//
+}
+```
+
+**Section order:**
+1. `using` declarations
+2. Custom errors
+3. Public constants
+4. Internal constants
+5. Public immutable stored properties
+6. Internal immutable stored properties
+7. Public stored properties
+8. Internal stored properties
+9. Constructor
+10. `receive` / `fallback`
+11. Modifiers
+12. External transactions
+13. External views
+14. Public transactions
+15. Internal helpers
+16. Internal views
+17. Private helpers
+
+Functions are alphabetized within each section.
+
+**Events:** Events are declared in interfaces only, never in implementation contracts. Implementations inherit events from their interface and emit them unqualified. This keeps the ABI definition in one place and allows tests to use interface-qualified event expectations (e.g., `emit IJBController.LaunchProject(...)`).
+
+## Interface Structure
+
+```solidity
+/// @notice One-line description.
+interface IJBExample is IJBBase {
+    // Events (with full NatSpec)
+
+    /// @notice Emitted when X happens.
+    /// @param projectId The ID of the project.
+    /// @param amount The amount transferred.
+    event SomethingHappened(uint256 indexed projectId, uint256 amount);
+
+    // Views (alphabetized)
+
+    /// @notice The directory of terminals and controllers.
+    function DIRECTORY() external view returns (IJBDirectory);
+
+    // State-changing functions (alphabetized)
+
+    /// @notice Does the thing.
+    /// @param projectId The ID of the project.
+    /// @return result The result.
+    function doThing(uint256 projectId) external returns (uint256 result);
+}
+```
+
+**Rules:**
+- Events first, then views, then state-changing functions
+- No custom errors in interfaces — errors belong in the implementing contract
+- Full NatSpec on every event, function, and parameter
+- Alphabetized within each group
+
+## Naming
+
+| Thing | Convention | Example |
+|-------|-----------|---------|
+| Contract | PascalCase | `JBMultiTerminal` |
+| Interface | `I` + PascalCase | `IJBMultiTerminal` |
+| Library | PascalCase | `JBCashOuts` |
+| Struct | PascalCase | `JBRulesetConfig` |
+| Enum | PascalCase | `JBApprovalStatus` |
+| Enum value | PascalCase | `ApprovalExpected` |
+| Error | `ContractName_ErrorName` | `JBMultiTerminal_FeeTerminalNotFound` |
+| Public constant | `ALL_CAPS` | `FEE`, `MAX_FEE` |
+| Internal constant | `_ALL_CAPS` | `_FEE_HOLDING_SECONDS` |
+| Public immutable | `ALL_CAPS` | `DIRECTORY`, `PERMISSIONS` |
+| Public/external function | `camelCase` | `cashOutTokensOf` |
+| Internal/private function | `_camelCase` | `_processFee` |
+| Internal storage | `_camelCase` | `_accountingContextForTokenOf` |
+| Function parameter | `camelCase` | `projectId`, `cashOutCount` |
+
+## NatSpec
+
+**Contracts:**
+```solidity
+/// @notice One-line description of what the contract does.
+contract JBExample is IJBExample {
+```
+
+**Functions:**
+```solidity
+/// @notice Records funds being added to a project's balance.
+/// @param projectId The ID of the project which funds are being added to.
+/// @param token The token being added.
+/// @param amount The amount added, as a fixed point number with the same decimals as the terminal.
+/// @return surplus The new surplus after adding.
+function recordAddedBalanceFor(
+    uint256 projectId,
+    address token,
+    uint256 amount
+) external override returns (uint256 surplus) {
+```
+
+**Structs:**
+```solidity
+/// @custom:member duration The number of seconds the ruleset lasts for. 0 means it never expires.
+/// @custom:member weight How many tokens to mint per unit paid (18 decimals).
+/// @custom:member weightCutPercent How much weight decays each cycle (9 decimals).
+struct JBRulesetConfig {
+    uint32 duration;
+    uint112 weight;
+    uint32 weightCutPercent;
+}
+```
+
+**Mappings:**
+```solidity
+/// @notice Context describing how a token is accounted for by a project.
+/// @custom:param projectId The ID of the project.
+/// @custom:param token The address of the token.
+mapping(uint256 projectId => mapping(address token => JBAccountingContext)) internal _accountingContextForTokenOf;
+```
+
+## Numbers
+
+Use underscores for thousands separators:
+
+```solidity
+uint256 internal constant _FEE_HOLDING_SECONDS = 2_419_200; // 28 days
+uint32 public constant MAX_WEIGHT_CUT_PERCENT = 1_000_000_000;
+uint256 public constant MAX_RESERVED_PERCENT = 10_000;
+```
+
+## Function Calls
+
+Use named parameters for readability when calling functions with 3+ arguments:
+
+```solidity
+PERMISSIONS.hasPermission({
+    operator: sender,
+    account: account,
+    projectId: projectId,
+    permissionId: permissionId,
+    includeRoot: true,
+    includeWildcardProjectId: true
+});
+```
+
+## Multiline Signatures
+
+```solidity
+function recordCashOutFor(
+    address holder,
+    uint256 projectId,
+    uint256 cashOutCount,
+    JBAccountingContext calldata accountingContext
+)
+    external
+    override
+    returns (
+        JBRuleset memory ruleset,
+        uint256 reclaimAmount,
+        JBCashOutHookSpecification[] memory hookSpecifications
+    )
+{
+```
+
+Modifiers and return types go on their own indented lines.
+
+## Error Handling
+
+- Validate inputs with explicit `revert` + custom error
+- Use `try-catch` only for external calls to untrusted contracts (hooks, fee processing)
+- Always include relevant context in error parameters
+
+```solidity
+// Direct validation
+if (amount > limit) revert JBTerminalStore_InadequateControllerPayoutLimit(amount, limit);
+
+// External call to untrusted hook
+try hook.afterPayRecordedWith(context) {} catch (bytes memory reason) {
+    emit HookAfterPayReverted(hook, context, reason, _msgSender());
+}
+```
+
+---
+
+## DevOps
+
+### foundry.toml
+
+Standard config for `@bananapus/core-v6`:
+
+```toml
+[profile.default]
+solc = '0.8.26'
+evm_version = 'cancun'
+optimizer_runs = 200
+libs = ["node_modules", "lib"]
+fs_permissions = [{ access = "read-write", path = "./"}]
+
+[profile.ci_sizes]
+optimizer_runs = 200
+
+[fuzz]
+runs = 4096
+
+[invariant]
+runs = 1024
+depth = 100
+fail_on_revert = false
+
+[fmt]
+number_underscore = "thousands"
+multiline_func_header = "all"
+wrap_comments = true
+```
+
+This is the standard config with no deviations.
+
+### CI Workflows
+
+Every repo has at minimum `test.yml` and `lint.yml`:
+
+**test.yml:**
+```yaml
+name: test
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+jobs:
+  forge-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22.4.x
+      - name: Install npm dependencies
+        run: npm install --omit=dev
+      - name: Install Foundry
+        uses: foundry-rs/foundry-toolchain@v1
+      - name: Run tests
+        run: forge test --fail-fast --summary --detailed --skip "*/script/**"
+      - name: Check contract sizes
+        run: FOUNDRY_PROFILE=ci_sizes forge build --sizes --skip "*/test/**" --skip "*/script/**" --skip SphinxUtils
+```
+
+**lint.yml:**
+```yaml
+name: lint
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+jobs:
+  forge-fmt:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install Foundry
+        uses: foundry-rs/foundry-toolchain@v1
+      - name: Check formatting
+        run: forge fmt --check
+```
+
+### package.json
+
+```json
+{
+  "name": "@bananapus/core-v6",
+  "version": "x.x.x",
+  "license": "MIT",
+  "repository": { "type": "git", "url": "git+https://github.com/Bananapus/nana-core-v6.git" },
+  "engines": { "node": ">=20.0.0" },
+  "scripts": {
+    "test": "forge test",
+    "coverage": "forge coverage --match-path \"./src/*.sol\" --report lcov --report summary"
+  },
+  "dependencies": { ... },
+  "devDependencies": {
+    "@sphinx-labs/plugins": "^0.33.2"
+  }
+}
+```
+
+**Scoping:** `@bananapus/` for Bananapus repos, `@rev-net/` for revnet, `@croptop/` for croptop, `@bannynet/` for banny, `@ballkidz/` for defifa.
+
+### remappings.txt
+
+Every repo has a `remappings.txt`. Minimal content:
+
+```
+@sphinx-labs/contracts/=lib/sphinx/packages/contracts/contracts/foundry
+```
+
+Additional mappings as needed for repo-specific dependencies.
+
+### Formatting
+
+Run `forge fmt` before committing. The `[fmt]` config in `foundry.toml` enforces:
+- Thousands separators on numbers (`1_000_000`)
+- Multiline function headers when multiple parameters
+- Wrapped comments at reasonable width
+
+CI checks formatting via `forge fmt --check`.
+
+### Branching
+
+- `main` is the primary branch
+- Feature branches for PRs
+- All PRs trigger test + lint workflows
+- Submodule checkout with `--recursive` in CI
+
+### Dependencies
+
+- Solidity dependencies via npm (`node_modules/`)
+- `forge-std` as a git submodule in `lib/`
+- Sphinx plugins as a devDependency
+- Cross-repo references use `file:../sibling-repo` in local development
+- Published versions use semver ranges (`^0.0.x`) for npm
+
+### Contract Size Checks
+
+CI runs `FOUNDRY_PROFILE=ci_sizes forge build --sizes` to catch contracts approaching the 24KB limit. The `ci_sizes` profile uses `optimizer_runs = 200` for realistic size measurement even when the default profile has different optimizer settings.

package/foundry.toml

@@ -1,6 +1,6 @@
 [profile.default]
 solc = '0.8.26'
-evm_version = 'paris'
+evm_version = 'cancun'
 optimizer_runs = 200
 libs = ["node_modules", "lib"]
 fs_permissions = [{ access = "read-write", path = "./"}]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/core-v6",
-  "version": "0.0.10",
+  "version": "0.0.12",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -26,7 +26,7 @@
     "artifacts": "source ./.env && npx sphinx artifacts --org-id 'ea165b21-7cdc-4d7b-be59-ecdd4c26bee4' --project-name 'nana-core-v6'"
   },
   "dependencies": {
-    "@bananapus/permission-ids-v6": "^0.0.5",
+    "@bananapus/permission-ids-v6": "^0.0.6",
     "@chainlink/contracts": "^1.3.0",
     "@openzeppelin/contracts": "^5.2.0",
     "@prb/math": "^4.1.0",

package/test/formal/BondingCurveProperties.t.sol

@@ -198,8 +198,8 @@ contract BondingCurveProperties is Test {
         if (firstResult + secondResult > singleResult) {
             // The excess should be tiny relative to the result
             uint256 excess = (firstResult + secondResult) - singleResult;
-            // Allow up to 1 basis point (0.01%) rounding tolerance
-            assert(excess * 10_000 <= singleResult);
+            // Allow up to 2 wei absolute (for small values) or 0.01% relative
+            assert(excess <= 2 || excess * 10_000 <= singleResult);
         }
     }
 
@@ -229,10 +229,13 @@ contract BondingCurveProperties is Test {
         uint256 secondResult = JBCashOuts.cashOutFrom(remainingSurplus, b, remainingSupply, cashOutTaxRate);
 
         // NOTE: Strict subadditivity violated due to mulDiv rounding.
-        // Verify the weaker property: excess bounded by rounding tolerance (< 0.01%).
+        // Verify the weaker property: excess bounded by rounding tolerance (<=2 wei or < 0.01%).
         if (firstResult + secondResult > singleResult) {
             uint256 excess = (firstResult + secondResult) - singleResult;
-            assertLe(excess * 10_000, singleResult, "No-arbitrage: rounding excess should be < 0.01%");
+            assertTrue(
+                excess <= 2 || excess * 10_000 <= singleResult,
+                "No-arbitrage: rounding excess should be <= 2 wei or < 0.01%"
+            );
         }
     }