@bananapus/permission-ids-v6 0.0.4 → 0.0.6

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,468 @@
+# 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 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 = "./"}]
+
+[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
+```
+
+**Variations:**
+- `evm_version = 'cancun'` for repos using transient storage (buyback-hook, router-terminal, univ4-router)
+- `via_ir = true` for repos hitting stack-too-deep (buyback-hook, banny-retail, univ4-lp-split-hook, deploy-all)
+- `optimizer = false` only for deploy-all-v6 (stack-too-deep with optimization)
+
+### 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/permission-ids-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.
+
+### 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,18 +1,20 @@
 [profile.default]
 solc = '0.8.26'
-evm_version = 'paris'                   # Required for L2s (Optimism, Arbitrum, etc.)
-match_contract = "_Local"               # Do not run fork tests
-sizes = true
-verbosity = 3                           # display errors
+evm_version = 'cancun'
 optimizer_runs = 200
-block_number = 14126430
-block_timestamp = 1643802347
-runs = 4096
 libs = ["node_modules", "lib"]
+fs_permissions = [{ access = "read-write", path = "./"}]
+
+[profile.ci_sizes]
+optimizer_runs = 200
+
+[fuzz]
+runs = 4096
 
-[profile.fork] # run via FOUNDRY_PROFILE=fork foundry test
-fs_permissions = [{ access = "read", path = "./deployments/mainnet" }] # Get the deployment addresses for forking
-match_contract = "_Fork"
+[invariant]
+runs = 1024
+depth = 100
+fail_on_revert = false
 
 [fmt]
 number_underscore = "thousands"

package/package.json

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

package/remappings.txt

@@ -0,0 +1 @@
+forge-std/=lib/forge-std/src/