@bananapus/permission-ids-v6 0.0.5 → 0.0.7

package/ADMINISTRATION.md

@@ -0,0 +1,106 @@
+# Administration
+
+Admin privileges and their scope in nana-permission-ids-v6.
+
+## Overview
+
+This repo defines permission ID constants. It contains no admin functions itself -- it is a reference library for the permission system used across the Juicebox V6 ecosystem. The constants in `JBPermissionIds` are consumed by contracts in nana-core-v6, nana-721-hook-v6, nana-buyback-hook-v6, nana-router-terminal-v6, and nana-suckers-v6 to gate privileged operations.
+
+There are no ownable contracts, no upgrade mechanisms, and no mutable state. The library compiles to inline constants.
+
+## Permission IDs
+
+All 32 defined permission IDs and what they control:
+
+| ID | Constant | Used By | What It Controls |
+|----|----------|---------|-----------------|
+| 1 | `ROOT` | All contracts | Grants every permission. See [ROOT Permission](#root-permission). |
+| 2 | `QUEUE_RULESETS` | nana-core | `JBController.queueRulesetsOf` -- queue new rulesets for a project. |
+| 3 | `LAUNCH_RULESETS` | nana-core | `JBController.launchRulesetsFor` -- launch a project's initial rulesets. Also requires `SET_TERMINALS` (ID 15). |
+| 4 | `CASH_OUT_TOKENS` | nana-core | `JBMultiTerminal.cashOutTokensOf` -- redeem tokens for surplus. Checked against the **token holder**, not the project owner. |
+| 5 | `SEND_PAYOUTS` | nana-core | `JBMultiTerminal.sendPayoutsOf` -- distribute payouts to splits. |
+| 6 | `MIGRATE_TERMINAL` | nana-core | `JBMultiTerminal.migrateBalanceOf` -- migrate a project's balance to another terminal. |
+| 7 | `SET_PROJECT_URI` | nana-core | `JBController.setUriOf` -- set project metadata URI. |
+| 8 | `DEPLOY_ERC20` | nana-core | `JBController.deployERC20For` -- deploy a new ERC-20 token for a project. |
+| 9 | `SET_TOKEN` | nana-core | `JBController.setTokenFor` -- set an existing ERC-20 token for a project. |
+| 10 | `MINT_TOKENS` | nana-core | `JBController.mintTokensOf` -- mint new project tokens. Only effective when the current ruleset allows owner minting. |
+| 11 | `BURN_TOKENS` | nana-core | `JBController.burnTokensOf` -- burn tokens. Checked against the **token holder**. |
+| 12 | `CLAIM_TOKENS` | nana-core | `JBController.claimTokensFor` -- claim internal credits as ERC-20. Checked against the **token holder**. |
+| 13 | `TRANSFER_CREDITS` | nana-core | `JBController.transferCreditsFrom` -- transfer internal credits. Checked against the **token holder**. |
+| 14 | `SET_CONTROLLER` | nana-core | `JBDirectory.setControllerOf` -- set a project's controller. |
+| 15 | `SET_TERMINALS` | nana-core | `JBDirectory.setTerminalsOf` -- set a project's terminals. **Warning:** can remove the primary terminal. |
+| 16 | `SET_PRIMARY_TERMINAL` | nana-core | `JBDirectory.setPrimaryTerminalOf` -- set the primary terminal for a token. |
+| 17 | `USE_ALLOWANCE` | nana-core | `JBMultiTerminal.useAllowanceOf` -- spend surplus allowance to an arbitrary address. |
+| 18 | `SET_SPLIT_GROUPS` | nana-core | `JBController.setSplitGroupsOf` -- configure payout and reserved token splits. |
+| 19 | `ADD_PRICE_FEED` | nana-core | `JBPrices.addPriceFeedFor` (via `JBController.addPriceFeed`) -- add a price feed for a project. |
+| 20 | `ADD_ACCOUNTING_CONTEXTS` | nana-core | `JBMultiTerminal.addAccountingContextsFor` -- add accepted tokens to a terminal. |
+| 21 | `ADJUST_721_TIERS` | nana-721-hook | `JB721TiersHook.adjustTiers` -- add or remove NFT tiers. |
+| 22 | `SET_721_METADATA` | nana-721-hook | `JB721TiersHook.setMetadata` -- set NFT metadata URIs. |
+| 23 | `MINT_721` | nana-721-hook | `JB721TiersHook.mintFor` -- manually mint NFTs to a beneficiary. |
+| 24 | `SET_721_DISCOUNT_PERCENT` | nana-721-hook | `JB721TiersHook.setDiscountPercentOf` -- set discount percent on NFT tiers. |
+| 25 | `SET_BUYBACK_TWAP` | nana-buyback-hook | `JBBuybackHook.setTwapWindowOf` -- configure the TWAP oracle window. |
+| 26 | `SET_BUYBACK_POOL` | nana-buyback-hook | `JBBuybackHook.setPoolFor` -- set the Uniswap pool for buybacks. |
+| 27 | `SET_BUYBACK_HOOK` | nana-buyback-hook | `JBBuybackHookRegistry.setHookFor` and `lockHookFor` -- configure and permanently lock the buyback hook. |
+| 28 | `SET_ROUTER_TERMINAL` | nana-router-terminal | `JBRouterTerminalRegistry.setTerminalFor` and `lockTerminalFor` -- configure and permanently lock the router terminal. |
+| 29 | `MAP_SUCKER_TOKEN` | nana-suckers | `JBSucker.mapToken` -- map an ERC-20 to its remote chain counterpart. Immutable once the outbox tree has entries. |
+| 30 | `DEPLOY_SUCKERS` | nana-suckers | `JBSuckerRegistry.deploySuckersFor` -- deploy sucker contracts for cross-chain bridging. |
+| 31 | `SUCKER_SAFETY` | nana-suckers | `JBSucker.enableEmergencyHatchFor` -- enable the emergency hatch to recover stuck tokens. |
+| 32 | `SET_SUCKER_DEPRECATION` | nana-suckers | `JBSucker.setDeprecation` -- set deprecation status (ENABLED, DEPRECATION_PENDING, SENDING_DISABLED, DEPRECATED). |
+
+IDs 0 and 33-255 are unused. ID 0 is reserved and cannot be set. IDs 33-255 are available for future ecosystem extensions.
+
+## ROOT Permission
+
+`ROOT` (ID 1) is a superuser permission. When an operator has ROOT for a given project, `JBPermissions` treats every permission check as passing for that project. It is the only permission that grants blanket access.
+
+Restrictions enforced by `JBPermissions`:
+
+- **Cannot be granted for the wildcard project ID (0).** Attempting to set ROOT with `projectId = 0` reverts with `JBPermissions_CantSetRootPermissionForWildcardProject()`. This prevents a single operator from controlling all projects owned by an account.
+- **ROOT operators cannot grant ROOT to others.** A ROOT operator can call `setPermissionsFor` on behalf of the account, but the new permission set must not include ROOT and must not target the wildcard project ID.
+- **ROOT is scoped per project.** Having ROOT for project 5 does not grant any permissions for project 6.
+
+## Wildcard Project ID
+
+When permissions are granted with `projectId = 0`, they apply to **every project** owned by the granting account. This is checked by `JBPermissions` as a fallback: if the operator does not have a specific permission for the target project, the contract checks whether the operator has that permission for `projectId = 0`.
+
+ROOT cannot be set for the wildcard project ID. All other permissions can.
+
+## How Permissions Are Checked
+
+Permissions are stored in `JBPermissions` as a 256-bit packed integer per (operator, account, projectId) tuple:
+
+```
+permissionsOf[operator][account][projectId] => uint256 (packed bits)
+```
+
+Each bit position corresponds to a permission ID. When a contract checks whether an operator has a permission, it calls `JBPermissions.hasPermission(operator, account, projectId, permissionId)`, which:
+
+1. Checks whether the operator has ROOT (bit 1) for the specific project -- if so, returns true.
+2. Checks whether the specific permission bit is set for the project.
+3. Falls back to checking the wildcard `projectId = 0` for both ROOT and the specific permission.
+
+Contracts that use this system inherit from `JBPermissioned`, which provides the `_requirePermissionFrom(account, projectId, permissionId)` modifier. This modifier passes if the caller is the account itself or has the required permission via `JBPermissions`.
+
+## High-Risk Permissions
+
+Some permissions warrant extra caution when granting:
+
+- **`ROOT` (1):** Full access to all gated functions for a project.
+- **`SET_TERMINALS` (15):** Can remove the primary terminal, breaking payments and cashouts.
+- **`USE_ALLOWANCE` (17):** Can send surplus funds to any address.
+- **`SET_BUYBACK_HOOK` (27):** Can permanently lock the buyback hook configuration.
+- **`SET_ROUTER_TERMINAL` (28):** Can permanently lock the router terminal configuration.
+- **`MINT_TOKENS` (10):** Can inflate token supply (subject to ruleset allowing owner minting).
+
+## Holder vs. Owner Permissions
+
+Most permissions are checked against the **project owner** (the account that owns the project NFT). Four permissions are instead checked against the **token holder**:
+
+| Permission | Checked Against |
+|-----------|----------------|
+| `CASH_OUT_TOKENS` (4) | Token holder |
+| `BURN_TOKENS` (11) | Token holder |
+| `CLAIM_TOKENS` (12) | Token holder |
+| `TRANSFER_CREDITS` (13) | Token holder |
+
+This means a token holder can grant an operator permission to cash out, burn, claim, or transfer their own tokens -- independent of the project owner's permissions.

package/ARCHITECTURE.md

@@ -0,0 +1,53 @@
+# nana-permission-ids-v6 — Architecture
+
+## Purpose
+
+Constants library defining permission IDs used throughout the Juicebox V6 ecosystem. These IDs are used with `JBPermissions` to control access to protocol functions.
+
+## Contract Map
+
+```
+src/
+└── JBPermissionIds.sol — Library of uint8 permission ID constants
+```
+
+## Permission ID Registry
+
+| ID | Name | Used By | Gated Function |
+|----|------|---------|----------------|
+| 1 | `ROOT` | nana-core | All permissions (dangerous) |
+| 2 | `QUEUE_RULESETS` | nana-core | `JBController.queueRulesetsOf` |
+| 3 | `LAUNCH_RULESETS` | nana-core | `JBController.launchRulesetsFor` |
+| 4 | `CASH_OUT_TOKENS` | nana-core | `JBMultiTerminal.cashOutTokensOf` |
+| 5 | `SEND_PAYOUTS` | nana-core | `JBMultiTerminal.sendPayoutsOf` |
+| 6 | `MIGRATE_TERMINAL` | nana-core | `JBMultiTerminal.migrateBalanceOf` |
+| 7 | `SET_PROJECT_URI` | nana-core | `JBController.setUriOf` |
+| 8 | `DEPLOY_ERC20` | nana-core | `JBController.deployERC20For` |
+| 9 | `SET_TOKEN` | nana-core | `JBController.setTokenFor` |
+| 10 | `MINT_TOKENS` | nana-core | `JBController.mintTokensOf` |
+| 11 | `BURN_TOKENS` | nana-core | `JBController.burnTokensOf` |
+| 12 | `CLAIM_TOKENS` | nana-core | `JBController.claimTokensFor` |
+| 13 | `TRANSFER_CREDITS` | nana-core | `JBController.transferCreditsFrom` |
+| 14 | `SET_CONTROLLER` | nana-core | `JBDirectory.setControllerOf` |
+| 15 | `SET_TERMINALS` | nana-core | `JBDirectory.setTerminalsOf` |
+| 16 | `SET_PRIMARY_TERMINAL` | nana-core | `JBDirectory.setPrimaryTerminalOf` |
+| 17 | `USE_ALLOWANCE` | nana-core | `JBMultiTerminal.useAllowanceOf` |
+| 18 | `SET_SPLIT_GROUPS` | nana-core | `JBController.setSplitGroupsOf` |
+| 19 | `ADD_PRICE_FEED` | nana-core | `JBPrices.addPriceFeedFor` |
+| 20 | `ADD_ACCOUNTING_CONTEXTS` | nana-core | `JBMultiTerminal.addAccountingContextsFor` |
+| 21 | `ADJUST_721_TIERS` | nana-721-hook | `JB721TiersHook.adjustTiers` |
+| 22 | `SET_721_METADATA` | nana-721-hook | `JB721TiersHook.setMetadata` |
+| 23 | `MINT_721` | nana-721-hook | `JB721TiersHook.mintFor` |
+| 24 | `SET_721_DISCOUNT_PERCENT` | nana-721-hook | `JB721TiersHook.setDiscountPercentOf` |
+| 25 | `SET_BUYBACK_TWAP` | nana-buyback-hook | `JBBuybackHook.setTwapWindowOf` |
+| 26 | `SET_BUYBACK_POOL` | nana-buyback-hook | `JBBuybackHook.setPoolFor` |
+| 27 | `SET_BUYBACK_HOOK` | nana-buyback-hook | `JBBuybackHookRegistry.setHookFor` + `lockHookFor` |
+| 28 | `SET_ROUTER_TERMINAL` | nana-router-terminal | `JBRouterTerminalRegistry.setTerminalFor` + `lockTerminalFor` |
+| 29 | `MAP_SUCKER_TOKEN` | nana-suckers | `JBSucker.mapToken` |
+| 30 | `DEPLOY_SUCKERS` | nana-suckers | `JBSuckerRegistry.deploySuckersFor` |
+| 31 | `SUCKER_SAFETY` | nana-suckers | `JBSucker.enableEmergencyHatchFor` |
+| 32 | `SET_SUCKER_DEPRECATION` | nana-suckers | `JBSucker.setDeprecation` |
+
+## Dependencies
+
+None — this is a leaf dependency with no imports.

package/RISKS.md

@@ -0,0 +1,21 @@
+# nana-permission-ids-v6 — Risks
+
+## Trust Assumptions
+
+This is a constants-only library with no runtime behavior. The risk surface is limited to the correctness of the ID assignments.
+
+## Known Risks
+
+| Risk | Description | Mitigation |
+|------|-------------|------------|
+| ID collision | If two repos use the same ID for different permissions, access control breaks | IDs are centrally managed in this single file |
+| ROOT scope | ROOT (ID 1) grants ALL permissions across all contracts | Cannot be set for wildcard projectId=0; ROOT operators cannot grant ROOT |
+| SET_TERMINALS scope | Includes ability to remove the primary terminal | Documented warning in source |
+| SET_BUYBACK_HOOK / SET_ROUTER_TERMINAL scope | Each gates both setting AND locking (permanent) | Documented in source; granting means operator can lock |
+
+## Design Notes
+
+- Permission 0 is reserved and cannot be set
+- IDs are `uint8` (0-255), with 1-32 currently assigned
+- IDs 33-255 are available for future ecosystem extensions
+- This library has zero dependencies — it is the leaf of the dependency graph

package/STYLE_GUIDE.md

@@ -0,0 +1,531 @@
+# 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.
+
+## 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 ---------------------------- //
+    //*********************************************************************//
+
+    //*********************************************************************//
+    // ---------------------- external transactions ---------------------- //
+    //*********************************************************************//
+
+    //*********************************************************************//
+    // ----------------------- external views ---------------------------- //
+    //*********************************************************************//
+
+    //*********************************************************************//
+    // ----------------------- public transactions ----------------------- //
+    //*********************************************************************//
+
+    //*********************************************************************//
+    // ----------------------- internal helpers -------------------------- //
+    //*********************************************************************//
+
+    //*********************************************************************//
+    // ----------------------- internal views ---------------------------- //
+    //*********************************************************************//
+
+    //*********************************************************************//
+    // ----------------------- private helpers --------------------------- //
+    //*********************************************************************//
+}
+```
+
+**Section order:**
+1. Custom errors
+2. Public constants
+3. Internal constants
+4. Public immutable stored properties
+5. Internal immutable stored properties
+6. Public stored properties
+7. Internal stored properties
+8. Constructor
+9. External transactions
+10. External views
+11. Public transactions
+12. Internal helpers
+13. Internal views
+14. Private helpers
+
+Functions are alphabetized within each section.
+
+## 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 across all repos:
+
+```toml
+[profile.default]
+solc = '0.8.26'
+evm_version = 'cancun'
+optimizer_runs = 200
+libs = ["node_modules", "lib"]
+fs_permissions = [{ access = "read-write", path = "./"}]
+
+[fuzz]
+runs = 4096
+
+[invariant]
+runs = 1024
+depth = 100
+fail_on_revert = false
+
+[fmt]
+number_underscore = "thousands"
+multiline_func_header = "all"
+wrap_comments = true
+```
+
+**Optional sections (add only when needed):**
+- `[rpc_endpoints]` — repos with fork tests. Maps named endpoints to env vars (e.g. `ethereum = "${RPC_ETHEREUM_MAINNET}"`).
+- `[profile.ci_sizes]` — only when CI needs different optimizer settings than defaults for the size check step (e.g. `optimizer_runs = 200` when the default profile uses a lower value).
+
+**Common variations:**
+- `via_ir = true` when hitting stack-too-deep
+- `optimizer = false` when optimization causes stack-too-deep
+- `optimizer_runs` reduced when deep struct nesting causes stack-too-deep at 200 runs
+
+### 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/**"
+        env:
+          RPC_ETHEREUM_MAINNET: ${{ secrets.RPC_ETHEREUM_MAINNET }}
+      - name: Check contract sizes
+        run: 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
+```
+
+**slither.yml** (repos with `src/` contracts only):
+```yaml
+name: slither
+on:
+    pull_request:
+      branches:
+        - main
+    push:
+      branches:
+        - main
+jobs:
+  analyze:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - uses: actions/setup-node@v4
+        with:
+          node-version: latest
+      - name: Install npm dependencies
+        run: npm install --omit=dev
+      - name: Install Foundry
+        uses: foundry-rs/foundry-toolchain@v1
+      - name: Run slither
+        uses: crytic/slither-action@v0.3.1
+        with:
+            slither-config: slither-ci.config.json
+            fail-on: medium
+```
+
+**slither-ci.config.json:**
+```json
+{
+  "detectors_to_exclude": "timestamp,uninitialized-local,naming-convention,solc-version,shadowing-local",
+  "exclude_informational": true,
+  "exclude_low": false,
+  "exclude_medium": false,
+  "exclude_high": false,
+  "disable_color": false,
+  "filter_paths": "(mocks/|test/|node_modules/|lib/)",
+  "legacy_ast": false
+}
+```
+
+**Variations:**
+- Deployer-only repos (no `src/`, only `script/`) skip slither entirely — the action's internal `forge build` skips `test/` and `script/` by default, leaving nothing to compile.
+- Use inline `// slither-disable-next-line <detector>` to suppress known false positives rather than adding to `detectors_to_exclude` in the config. The comment must be on the line immediately before the flagged expression.
+
+### package.json
+
+```json
+{
+  "name": "@bananapus/package-name-v6",
+  "version": "x.x.x",
+  "license": "MIT",
+  "repository": { "type": "git", "url": "git+https://github.com/Org/repo.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.
+
+### Linting
+
+Solar (Foundry's built-in linter) runs automatically during `forge build`. It scans all `.sol` files in `libs` directories, including `node_modules`.
+
+**All test helpers must use relative imports** (e.g. `../../src/structs/JBRuleset.sol`), not bare `src/` imports. This ensures solar can resolve paths when the helper is consumed via npm in downstream repos.
+
+### Fork Tests
+
+Fork tests use named RPC endpoints defined in `[rpc_endpoints]` of `foundry.toml`. No skip guards — fork tests should hard-fail if the RPC endpoint is unavailable, making CI failures explicit.
+
+```solidity
+function setUp() public {
+    vm.createSelectFork("ethereum");
+    // ... setup code
+}
+```
+
+The endpoint name (e.g. `"ethereum"`) maps to an env var via `foundry.toml`:
+
+```toml
+[rpc_endpoints]
+ethereum = "${RPC_ETHEREUM_MAINNET}"
+```
+
+For multi-chain fork tests, add all needed endpoints.
+
+### 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 `forge build --sizes` to catch contracts approaching the 24KB limit. When the repo's default `optimizer_runs` differs from what you want for size checking, use `FOUNDRY_PROFILE=ci_sizes forge build --sizes` with a `[profile.ci_sizes]` section in `foundry.toml`.

package/foundry.toml

@@ -1,13 +1,10 @@
 [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 = "./"}]
 
-[profile.ci_sizes]
-optimizer_runs = 200
-
 [fuzz]
 runs = 4096
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/permission-ids-v6",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "license": "MIT",
   "repository": {
     "type": "git",