@bananapus/permission-ids-v6 0.0.10 → 0.0.11

package/ADMINISTRATION.md

@@ -14,39 +14,39 @@ All 33 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 | `JBController.addPriceFeed` (which internally calls `JBPrices.addPriceFeedFor`) -- add a price feed for a project. |
-| 20 | `ADD_ACCOUNTING_CONTEXTS` | nana-core | `JBMultiTerminal.addAccountingContextsFor` -- add accepted tokens to a terminal. |
-| 21 | `SET_TOKEN_METADATA` | nana-core | `JBController.setTokenMetadataOf` -- set a project token's name and symbol. |
-| 22 | `ADJUST_721_TIERS` | nana-721-hook | `JB721TiersHook.adjustTiers` -- add or remove NFT tiers. |
-| 23 | `SET_721_METADATA` | nana-721-hook | `JB721TiersHook.setMetadata` -- set NFT metadata URIs. |
-| 24 | `MINT_721` | nana-721-hook | `JB721TiersHook.mintFor` -- manually mint NFTs to a beneficiary. |
-| 25 | `SET_721_DISCOUNT_PERCENT` | nana-721-hook | `JB721TiersHook.setDiscountPercentOf` -- set discount percent on NFT tiers. |
-| 26 | `SET_BUYBACK_TWAP` | nana-buyback-hook | `JBBuybackHook.setTwapWindowOf` -- configure the TWAP oracle window. |
-| 27 | `SET_BUYBACK_POOL` | nana-buyback-hook | `JBBuybackHook.setPoolFor` -- set the Uniswap pool for buybacks. |
-| 28 | `SET_BUYBACK_HOOK` | nana-buyback-hook | `JBBuybackHookRegistry.setHookFor` and `lockHookFor` -- configure and permanently lock the buyback hook. |
-| 29 | `SET_ROUTER_TERMINAL` | nana-router-terminal | `JBRouterTerminalRegistry.setTerminalFor` and `lockTerminalFor` -- configure and permanently lock the router terminal. |
-| 30 | `MAP_SUCKER_TOKEN` | nana-suckers | `JBSucker.mapToken` -- map an ERC-20 to its remote chain counterpart. Immutable once the outbox tree has entries. |
-| 31 | `DEPLOY_SUCKERS` | nana-suckers | `JBSuckerRegistry.deploySuckersFor` -- deploy sucker contracts for cross-chain bridging. |
-| 32 | `SUCKER_SAFETY` | nana-suckers | `JBSucker.enableEmergencyHatchFor` -- enable the emergency hatch to recover stuck tokens. |
-| 33 | `SET_SUCKER_DEPRECATION` | nana-suckers | `JBSucker.setDeprecation` -- set deprecation status (ENABLED, DEPRECATION_PENDING, SENDING_DISABLED, DEPRECATED). |
+| 1 | `ROOT` | All contracts (via `JBPermissions`) | Grants every permission. See [ROOT Permission](#root-permission). |
+| 2 | `QUEUE_RULESETS` | nana-core (`JBController`) | `JBController.queueRulesetsOf` -- queue new rulesets for a project. |
+| 3 | `LAUNCH_RULESETS` | nana-core (`JBController`) | `JBController.launchRulesetsFor` -- launch a project's initial rulesets. Also requires `SET_TERMINALS` (ID 15). |
+| 4 | `CASH_OUT_TOKENS` | nana-core (`JBMultiTerminal`) | `JBMultiTerminal.cashOutTokensOf` -- redeem tokens for surplus. Checked against the **token holder**, not the project owner. |
+| 5 | `SEND_PAYOUTS` | nana-core (`JBMultiTerminal`) | `JBMultiTerminal.sendPayoutsOf` -- distribute payouts to splits. |
+| 6 | `MIGRATE_TERMINAL` | nana-core (`JBMultiTerminal`) | `JBMultiTerminal.migrateBalanceOf` -- migrate a project's balance to another terminal. |
+| 7 | `SET_PROJECT_URI` | nana-core (`JBController`) | `JBController.setUriOf` -- set project metadata URI. |
+| 8 | `DEPLOY_ERC20` | nana-core (`JBController`) | `JBController.deployERC20For` -- deploy a new ERC-20 token for a project. |
+| 9 | `SET_TOKEN` | nana-core (`JBController`) | `JBController.setTokenFor` -- set an existing ERC-20 token for a project. |
+| 10 | `MINT_TOKENS` | nana-core (`JBController`) | `JBController.mintTokensOf` -- mint new project tokens. Only effective when the current ruleset allows owner minting. |
+| 11 | `BURN_TOKENS` | nana-core (`JBController`) | `JBController.burnTokensOf` -- burn tokens. Checked against the **token holder**. |
+| 12 | `CLAIM_TOKENS` | nana-core (`JBController`) | `JBController.claimTokensFor` -- claim internal credits as ERC-20. Checked against the **token holder**. |
+| 13 | `TRANSFER_CREDITS` | nana-core (`JBController`) | `JBController.transferCreditsFrom` -- transfer internal credits. Checked against the **token holder**. |
+| 14 | `SET_CONTROLLER` | nana-core (`JBDirectory`) | `JBDirectory.setControllerOf` -- set a project's controller. |
+| 15 | `SET_TERMINALS` | nana-core (`JBDirectory`) | `JBDirectory.setTerminalsOf` -- set a project's terminals. **Warning:** can remove the primary terminal. |
+| 16 | `SET_PRIMARY_TERMINAL` | nana-core (`JBDirectory`) | `JBDirectory.setPrimaryTerminalOf` -- set the primary terminal for a token. |
+| 17 | `USE_ALLOWANCE` | nana-core (`JBMultiTerminal`) | `JBMultiTerminal.useAllowanceOf` -- spend surplus allowance to an arbitrary address. |
+| 18 | `SET_SPLIT_GROUPS` | nana-core (`JBController`) | `JBController.setSplitGroupsOf` -- configure payout and reserved token splits. |
+| 19 | `ADD_PRICE_FEED` | nana-core (`JBController`) | `JBController.addPriceFeedFor` (which internally calls `JBPrices.addPriceFeedFor`) -- add a price feed for a project. |
+| 20 | `ADD_ACCOUNTING_CONTEXTS` | nana-core (`JBMultiTerminal`) | `JBMultiTerminal.addAccountingContextsFor` -- add accepted tokens to a terminal. |
+| 21 | `SET_TOKEN_METADATA` | nana-core (`JBController`) | `JBController.setTokenMetadataOf` -- set a project token's name and symbol. |
+| 22 | `ADJUST_721_TIERS` | nana-721-hook (`JB721TiersHook`) | `JB721TiersHook.adjustTiers` -- add or remove NFT tiers. |
+| 23 | `SET_721_METADATA` | nana-721-hook (`JB721TiersHook`) | `JB721TiersHook.setMetadata` -- set NFT metadata URIs. |
+| 24 | `MINT_721` | nana-721-hook (`JB721TiersHook`) | `JB721TiersHook.mintFor` -- manually mint NFTs to a beneficiary. |
+| 25 | `SET_721_DISCOUNT_PERCENT` | nana-721-hook (`JB721TiersHook`) | `JB721TiersHook.setDiscountPercentOf` -- set discount percent on NFT tiers. |
+| 26 | `SET_BUYBACK_TWAP` | nana-buyback-hook (`JBBuybackHook`) | `JBBuybackHook.setTwapWindowOf` -- configure the TWAP oracle window. |
+| 27 | `SET_BUYBACK_POOL` | nana-buyback-hook (`JBBuybackHook`) | `JBBuybackHook.setPoolFor` -- set the Uniswap pool for buybacks. |
+| 28 | `SET_BUYBACK_HOOK` | nana-buyback-hook (`JBBuybackHookRegistry`) | `JBBuybackHookRegistry.setHookFor` and `lockHookFor` -- configure and permanently lock the buyback hook. |
+| 29 | `SET_ROUTER_TERMINAL` | nana-router-terminal (`JBRouterTerminalRegistry`) | `JBRouterTerminalRegistry.setTerminalFor` and `lockTerminalFor` -- configure and permanently lock the router terminal. |
+| 30 | `MAP_SUCKER_TOKEN` | nana-suckers (`JBSucker`) | `JBSucker.mapToken` -- map an ERC-20 to its remote chain counterpart. Immutable once the outbox tree has entries. |
+| 31 | `DEPLOY_SUCKERS` | nana-suckers (`JBSuckerRegistry`) | `JBSuckerRegistry.deploySuckersFor` -- deploy sucker contracts for cross-chain bridging. |
+| 32 | `SUCKER_SAFETY` | nana-suckers (`JBSucker`) | `JBSucker.enableEmergencyHatchFor` -- enable the emergency hatch to recover stuck tokens. |
+| 33 | `SET_SUCKER_DEPRECATION` | nana-suckers (`JBSucker`) | `JBSucker.setDeprecation` -- set deprecation status (ENABLED, DEPRECATION_PENDING, SENDING_DISABLED, DEPRECATED). |
 
 IDs 0 and 34-255 are unused. ID 0 is reserved and cannot be set. IDs 34-255 are available for future ecosystem extensions.
 
@@ -74,11 +74,14 @@ Permissions are stored in `JBPermissions` as a 256-bit packed integer per (opera
 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:
+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, includeRoot, includeWildcardProjectId)`, 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.
+2. If `includeWildcardProjectId`, checks whether the operator has ROOT (bit 1) for the wildcard project (`projectId = 0`) -- if so, returns true.
+3. Checks whether the specific permission bit is set for the specific project -- if so, returns true.
+4. If `includeWildcardProjectId`, checks whether the specific permission bit is set for the wildcard project (`projectId = 0`) -- if so, returns true.
+
+Steps 1-2 are skipped if `includeRoot` is false. Steps 2 and 4 are skipped if `includeWildcardProjectId` is false.
 
 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`.
 

package/ARCHITECTURE.md

@@ -4,6 +4,18 @@
 
 Constants library defining permission IDs used throughout the Juicebox V6 ecosystem. These IDs are used with `JBPermissions` to control access to protocol functions.
 
+## How Permissions Work
+
+These IDs plug into `JBPermissions` in nana-core, which stores permissions as a 256-bit packed `uint256` — one bit per permission ID. Callers check access via `hasPermission(operator, account, projectId, permissionId)`. A project owner can grant any operator a set of permission IDs scoped to a specific project, or use `projectId = 0` as a wildcard to grant permissions across all projects.
+
+## Permission Guards
+
+`JBPermissions.setPermissionsFor` enforces three guard rules:
+
+- **Permission 0 is reserved.** Setting bit 0 always reverts (`JBPermissions_NoZeroPermission`). This prevents accidental misuse of an uninitialized permission ID.
+- **Wildcard scope requires the account itself.** An operator with ROOT on a specific project cannot use `setPermissionsFor` with `projectId = 0` (wildcard). This prevents a single-project ROOT operator from escalating to all-project access. Reverts with `JBPermissions_Unauthorized`.
+- **ROOT operators cannot grant ROOT to others.** Only the account itself can include `ROOT` (ID 1) in a `setPermissionsFor` call. A ROOT operator calling on behalf of the account will revert if the new permission set includes ROOT.
+
 ## Contract Map
 
 ```
@@ -33,7 +45,7 @@ src/
 | 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 | `JBController.addPriceFeed` |
+| 19 | `ADD_PRICE_FEED` | nana-core | `JBController.addPriceFeedFor` |
 | 20 | `ADD_ACCOUNTING_CONTEXTS` | nana-core | `JBMultiTerminal.addAccountingContextsFor` |
 | 21 | `SET_TOKEN_METADATA` | nana-core | `JBController.setTokenMetadataOf` |
 | 22 | `ADJUST_721_TIERS` | nana-721-hook | `JB721TiersHook.adjustTiers` |

package/AUDIT_INSTRUCTIONS.md

@@ -2,6 +2,42 @@
 
 You are auditing a constants-only library that defines all permission IDs used across the Juicebox V6 ecosystem. The library has no state, no functions, no constructors, and no dependencies. The entire audit surface is the correctness and consistency of 33 `uint8` constants. Read [RISKS.md](./RISKS.md) first -- it documents all known risks and trust assumptions. Then come back here.
 
+## Quick Verification
+
+Run this one-liner from the repo root to verify all 33 permission IDs are unique, sequential (1-33), and have no gaps or duplicates:
+
+```bash
+grep 'constant.*=' src/JBPermissionIds.sol | sed 's/.*= \([0-9]*\).*/\1/' | sort -n | diff - <(seq 1 33) && echo "PASS: All 33 IDs are unique and sequential (1-33)" || echo "FAIL: ID mismatch detected"
+```
+
+If `PASS` is printed, the constants are correctly assigned. If `FAIL` is printed, inspect the diff output to identify which IDs are missing, duplicated, or out of range.
+
+## Compiler and Version Info
+
+From `foundry.toml`:
+
+| Setting | Value |
+|---------|-------|
+| Solidity version | `0.8.28` |
+| EVM target | `cancun` |
+| Optimizer | Enabled, 200 runs |
+| Pragma in source | `^0.8.0` (flexible, compiled with 0.8.28) |
+
+Note: The library pragma is `^0.8.0` rather than a fixed version, since consuming contracts may compile it with their own Solidity version. The `foundry.toml` pins `0.8.28` for local builds.
+
+## Previous Audit Findings
+
+A Nemesis audit (Feynman + State Inconsistency methodology) was conducted on 2026-03-17. Full results are in [`.audit/findings/nemesis-verified.md`](./.audit/findings/nemesis-verified.md).
+
+**Result: 0 Critical | 0 High | 0 Medium | 2 Low (comment inaccuracies)**
+
+| ID | Severity | Summary | Status |
+|----|----------|---------|--------|
+| NM-001 | LOW | `ADD_PRICE_FEED` comment misidentifies gated contract (`JBPrices.addPriceFeedFor` vs actual `JBController.addPriceFeedFor`) | Fixed |
+| NM-002 | LOW | `SET_TOKEN_METADATA` comment uses wrong function name (`setMetadataOf` vs actual `setTokenMetadataOf`) | Fixed |
+
+Both findings were comment-only inaccuracies with no security impact. All 5 invariants (uniqueness, completeness, type consistency, no ID 0, sequential assignment) passed. Cross-repo verification confirmed correct usage across 7 consuming repos.
+
 ## Scope
 
 **In scope:**
@@ -48,7 +84,7 @@ permissionsOf[operator][account][projectId] => uint256 (one bit per permission I
 | 16 | `SET_PRIMARY_TERMINAL` | `JBDirectory.setPrimaryTerminalOf` | Project owner |
 | 17 | `USE_ALLOWANCE` | `JBMultiTerminal.useAllowanceOf` | Project owner |
 | 18 | `SET_SPLIT_GROUPS` | `JBController.setSplitGroupsOf` | Project owner |
-| 19 | `ADD_PRICE_FEED` | `JBController.addPriceFeed` (not `JBPrices` directly) | Project owner |
+| 19 | `ADD_PRICE_FEED` | `JBController.addPriceFeedFor` (not `JBPrices` directly) | Project owner |
 | 20 | `ADD_ACCOUNTING_CONTEXTS` | `JBMultiTerminal.addAccountingContextsFor` | Project owner |
 | 21 | `SET_TOKEN_METADATA` | `JBController.setTokenMetadataOf` | Project owner |
 | 22 | `ADJUST_721_TIERS` | `JB721TiersHook.adjustTiers` | Hook owner |
@@ -84,8 +120,6 @@ Each constant's doc comment claims it gates a specific function. Verify against
 - **nana-router-terminal-v6**: ID 29 should match permission checks in `JBRouterTerminalRegistry`.
 - **nana-suckers-v6**: IDs 30-33 should match permission checks in `JBSucker` and `JBSuckerRegistry`.
 
-Known discrepancy to investigate: **SET_BUYBACK_HOOK (ID 28)** -- the source comment says it gates `JBBuybackHookRegistry.setHookFor` and `lockHookFor`, but those functions may actually check `SET_BUYBACK_POOL` (ID 27) instead. Verify which ID is actually checked in the registry code and whether this mismatch causes any practical issue.
-
 ### 3. Holder-Scoped vs Owner-Scoped Permissions
 
 Four permissions are checked against the **token holder**, not the project owner:

package/CHANGE_LOG.md

@@ -2,6 +2,15 @@
 
 This document describes all changes between `nana-permission-ids` (v5) and `nana-permission-ids-v6` (v6).
 
+## Summary
+
+- **All numeric IDs shifted** — the insertion of `LAUNCH_RULESETS` at ID 3 cascades through every subsequent permission. Any code using hardcoded numeric values will break.
+- **Two permissions split**: `QUEUE_RULESETS` → `QUEUE_RULESETS` + `LAUNCH_RULESETS`; `SUCKER_SAFETY` → `SUCKER_SAFETY` + `SET_SUCKER_DEPRECATION`.
+- **5 new permissions** added: `LAUNCH_RULESETS` (3), `SET_TOKEN_METADATA` (21), `SET_BUYBACK_HOOK` (28), `SET_ROUTER_TERMINAL` (29), `SET_SUCKER_DEPRECATION` (33).
+- **2 swap terminal permissions removed**: `ADD_SWAP_TERMINAL_POOL` and `ADD_SWAP_TERMINAL_TWAP_PARAMS` (swap terminal replaced by router terminal).
+
+> **⚠️ WARNING: All numeric permission IDs have shifted.** If your contracts, scripts, or frontends hardcode permission ID numbers (e.g., `permissions.setPermissionsFor(..., 3, ...)` for `CASH_OUT_TOKENS`), they MUST be updated. `CASH_OUT_TOKENS` moved from 3 → 4, `SEND_PAYOUTS` from 4 → 5, and so on. Always reference the named constants from `JBPermissionIds` rather than raw numbers.
+
 ---
 
 ## 1. Breaking Changes
@@ -48,6 +57,8 @@ In v5, `QUEUE_RULESETS` (2) granted permission to call both `JBController.queueR
 - `QUEUE_RULESETS` (2) -- only `JBController.queueRulesetsOf`
 - `LAUNCH_RULESETS` (3) -- only `JBController.launchRulesetsFor`
 
+> **Cross-repo impact**: `nana-core-v6` (`JBController.launchRulesetsFor`) now requires `LAUNCH_RULESETS` instead of `QUEUE_RULESETS`. `nana-omnichain-deployers-v6` and `revnet-core-v6` both use the new `LAUNCH_RULESETS` permission.
+
 ### `SUCKER_SAFETY` split into two permissions
 
 In v5, `SUCKER_SAFETY` (30) granted permission to call both `BPSucker.enableEmergencyHatchFor` and `BPSucker.setDeprecation`. In v6, these are separate:
@@ -64,6 +75,8 @@ The following permissions from `nana-swap-terminal` no longer exist in v6:
 | `ADD_SWAP_TERMINAL_POOL` | 26 | Was for `JBSwapTerminal.addDefaultPool` |
 | `ADD_SWAP_TERMINAL_TWAP_PARAMS` | 27 | Was for `JBSwapTerminal.addTwapParamsFor` |
 
+> **Cross-repo impact**: `nana-router-terminal-v6` (the replacement for swap terminal) uses the new `SET_ROUTER_TERMINAL` (29) permission instead.
+
 ### Contract prefix rename (suckers)
 
 Sucker contract references changed from `BP*` to `JB*`:

package/README.md

@@ -18,6 +18,15 @@ permissionsOf[operator][account][projectId] => uint256 (packed bits)
 |----------|-------------|
 | `JBPermissionIds` | Solidity library with 33 `uint8 internal constant` permission IDs (values 1--33). No state, no functions, no dependencies. Pragma `^0.8.0` for maximum compatibility. |
 
+## Repository Layout
+
+```
+src/
+└── JBPermissionIds.sol  ── 33 uint8 constants (the only source file)
+```
+
+No tests, interfaces, or deployment scripts -- this repo is a pure constant library.
+
 ## All permission IDs
 
 ### Global (ID 1)
@@ -47,7 +56,7 @@ permissionsOf[operator][account][projectId] => uint256 (packed bits)
 | 16 | `SET_PRIMARY_TERMINAL` | `JBDirectory.setPrimaryTerminalOf` | Set a project's primary terminal for a given token. |
 | 17 | `USE_ALLOWANCE` | `JBMultiTerminal.useAllowanceOf` | Use a project's surplus allowance to send funds to an arbitrary address. |
 | 18 | `SET_SPLIT_GROUPS` | `JBController.setSplitGroupsOf` | Set a project's split groups (how payouts and reserved tokens are distributed). |
-| 19 | `ADD_PRICE_FEED` | `JBController.addPriceFeed` | Add a price feed for a project. The controller checks this permission before calling `JBPrices.addPriceFeedFor`. |
+| 19 | `ADD_PRICE_FEED` | `JBController.addPriceFeedFor` | Add a price feed for a project. The controller checks this permission before calling `JBPrices.addPriceFeedFor`. |
 | 20 | `ADD_ACCOUNTING_CONTEXTS` | `JBMultiTerminal.addAccountingContextsFor` | Add accounting contexts (accepted tokens) to a terminal for a project. |
 | 21 | `SET_TOKEN_METADATA` | `JBController.setTokenMetadataOf` | Set a project token's name and symbol. Checked against the project owner. |
 
@@ -65,8 +74,8 @@ permissionsOf[operator][account][projectId] => uint256 (packed bits)
 | ID | Name | Checked in | Description |
 |----|------|------------|-------------|
 | 26 | `SET_BUYBACK_TWAP` | `JBBuybackHook.setTwapWindowOf` | Set the TWAP (time-weighted average price) oracle window for a project's buyback hook. |
-| 27 | `SET_BUYBACK_POOL` | `JBBuybackHook.setPoolFor`, `JBBuybackHookRegistry.setHookFor`, `JBBuybackHookRegistry.lockHookFor` | Set the Uniswap pool for a project's buyback. Also guards setting and locking the hook in `JBBuybackHookRegistry`. |
-| 28 | `SET_BUYBACK_HOOK` | *Reserved / revnet-core-v6* | Defined in `JBPermissionIds` for `JBBuybackHookRegistry.setHookFor` and `lockHookFor`, but the registry currently checks `SET_BUYBACK_POOL` (ID 27) for those functions. Used by `REVDeployer` in revnet-core-v6 as an operator permission grant. |
+| 27 | `SET_BUYBACK_POOL` | `JBBuybackHook.setPoolFor`, `JBBuybackHook.initializePoolFor`, `JBBuybackHookRegistry.setPoolFor`, `JBBuybackHookRegistry.initializePoolFor` | Set the Uniswap pool for a project's buyback hook. |
+| 28 | `SET_BUYBACK_HOOK` | `JBBuybackHookRegistry.setHookFor`, `JBBuybackHookRegistry.lockHookFor` | Set or lock the buyback hook in the registry. Also used by `REVDeployer` as an operator permission grant. |
 
 ### Router Terminal (ID 29) -- [nana-router-terminal-v6](https://github.com/Bananapus/nana-router-terminal-v6)
 

package/RISKS.md

@@ -9,10 +9,13 @@ Constants-only library defining permission ID values used throughout the Bananap
 - **SET_ROUTER_TERMINAL includes lock (ID 29).** Gates both `setTerminalFor` and `lockTerminalFor`. An operator can permanently lock the router terminal.
 - **ID collision risk.** Permission IDs are manually assigned sequential uint8 values. Adding new IDs requires coordination to avoid collision. Library is append-only.
 - **No runtime enforcement.** This library only defines constants. Enforcement happens in consuming contracts. A mismatch between the ID used here and the ID checked in a consumer would silently fail.
+- **High-impact permission IDs (fund-moving).** IDs that control fund flow should receive the most audit scrutiny: `ROOT` (1, grants everything), `CASH_OUT_TOKENS` (4, triggers withdrawals), `SEND_PAYOUTS` (5, triggers payout distribution), `MIGRATE_TERMINAL` (6, moves balances), `SET_TERMINALS` (15, redirects all fund flows), `USE_ALLOWANCE` (17, draws from surplus), `SET_SPLIT_GROUPS` (18, controls where payouts go). Of these, ROOT + SET_TERMINALS + MIGRATE_TERMINAL are the most dangerous — they can redirect all of a project's funds.
+- **Wildcard `projectId=0` semantics.** When a permission is granted with `projectId=0`, it applies to ALL projects. This is used by system contracts (e.g., `REVLoans` gets `USE_ALLOWANCE` with `projectId=0`). A bug in a contract holding wildcard permissions affects every project in the ecosystem, not just one. Only system-level contracts should hold wildcard permissions.
 
 ## 2. Design Notes
 
 - Permission 0 is reserved and cannot be set.
 - IDs are `uint8` (0-255), with 1-33 currently assigned.
 - IDs 34-255 are available for future ecosystem extensions.
+- IDs 34-255 are available for ecosystem extensions. Third-party contracts can define their own permission IDs in this range, but must coordinate to avoid collisions. No on-chain registry exists for custom IDs — collision detection is purely social.
 - This library has zero dependencies -- it is the leaf of the dependency graph.

package/SKILLS.md

@@ -16,16 +16,7 @@ N/A -- this is a constants-only library with no callable functions.
 
 ## How permissions work
 
-Permissions are stored in `JBPermissions` as a 256-bit packed integer:
-
-```
-permissionsOf[operator][account][projectId] => uint256 (one bit per permission ID)
-```
-
-When a permissioned function is called, the contract checks whether the caller either **is** the account or **has** the required permission ID for that project. The check also considers:
-
-1. **ROOT override** -- if the operator has ROOT (ID 1) for the project (or wildcard), all permission checks pass.
-2. **Wildcard project ID** -- permissions granted with `projectId = 0` apply to all projects for that account.
+Permissions are stored as 256-bit packed integers in `JBPermissions`, keyed by `[operator][account][projectId]`. ROOT (ID 1) passes all checks; `projectId = 0` grants cross-project access. See `nana-core-v6/SKILLS.md` for full permissions mechanics.
 
 ## All Permission IDs
 
@@ -56,7 +47,7 @@ When a permissioned function is called, the contract checks whether the caller e
 | 16 | `SET_PRIMARY_TERMINAL` | `JBDirectory.setPrimaryTerminalOf` | Set the primary terminal for a given token. Checked against project owner. |
 | 17 | `USE_ALLOWANCE` | `JBMultiTerminal.useAllowanceOf` | Use surplus allowance to send funds to an arbitrary address. Checked against project owner. |
 | 18 | `SET_SPLIT_GROUPS` | `JBController.setSplitGroupsOf` | Set how payouts and reserved tokens are distributed. Checked against project owner. |
-| 19 | `ADD_PRICE_FEED` | `JBController.addPriceFeed` | Add a price feed for a project. The controller checks this permission, then calls `JBPrices.addPriceFeedFor` internally. Checked against project owner. |
+| 19 | `ADD_PRICE_FEED` | `JBController.addPriceFeedFor` | Add a price feed for a project. The controller checks this permission, then calls `JBPrices.addPriceFeedFor` internally. Checked against project owner. |
 | 20 | `ADD_ACCOUNTING_CONTEXTS` | `JBMultiTerminal.addAccountingContextsFor` | Add accepted token accounting contexts to a terminal. Checked against project owner. |
 | 21 | `SET_TOKEN_METADATA` | `JBController.setTokenMetadataOf` | Set a project token's name and symbol. Checked against project owner. |
 
@@ -74,8 +65,8 @@ When a permissioned function is called, the contract checks whether the caller e
 | ID | Name | Checked in | Permission scope |
 |----|------|------------|-----------------|
 | 26 | `SET_BUYBACK_TWAP` | `JBBuybackHook.setTwapWindowOf` | Set the TWAP oracle window duration. Checked against project owner. |
-| 27 | `SET_BUYBACK_POOL` | `JBBuybackHook.setPoolFor`, `JBBuybackHookRegistry.setHookFor`, `JBBuybackHookRegistry.lockHookFor` | Set the Uniswap pool for a project's buyback. Also guards setting and locking the hook in `JBBuybackHookRegistry`. Checked against project owner. |
-| 28 | `SET_BUYBACK_HOOK` | *Currently unused in buyback hook code* | Defined for `JBBuybackHookRegistry.setHookFor` and `lockHookFor` per the source comment, but the registry actually checks `SET_BUYBACK_POOL` (ID 27) for those functions. Referenced by `REVDeployer` in revnet-core-v6 as an operator permission grant. |
+| 27 | `SET_BUYBACK_POOL` | `JBBuybackHook.setPoolFor`, `JBBuybackHook.initializePoolFor`, `JBBuybackHookRegistry.initializePoolFor` | Set the Uniswap pool for a project's buyback. Checked against project owner. |
+| 28 | `SET_BUYBACK_HOOK` | `JBBuybackHookRegistry.setHookFor`, `JBBuybackHookRegistry.lockHookFor` | Set or lock the buyback hook implementation for a project. Checked against project owner. Also granted by `REVDeployer` as an operator permission. |
 
 ### nana-router-terminal-v6
 
@@ -92,6 +83,20 @@ When a permissioned function is called, the contract checks whether the caller e
 | 32 | `SUCKER_SAFETY` | `JBSucker.enableEmergencyHatchFor` | Enable the emergency hatch to recover stuck tokens. Checked against project owner. |
 | 33 | `SET_SUCKER_DEPRECATION` | `JBSucker.setDeprecation` | Move a sucker through the deprecation lifecycle (ENABLED -> DEPRECATION_PENDING -> SENDING_DISABLED -> DEPRECATED). Checked against project owner. |
 
+## Common Permission Bundles
+
+Typical combinations when granting operator access via `JBPermissions.setPermissionsFor`:
+
+| Bundle | IDs | Use case |
+|--------|-----|----------|
+| **Deployer operator** | `QUEUE_RULESETS` (2), `SET_SPLIT_GROUPS` (18), `SET_FUND_ACCESS_LIMITS` (not in this library -- set via ruleset config) | Operator that manages project rulesets and split configuration on behalf of the owner. |
+| **Token manager** | `MINT_TOKENS` (10), `BURN_TOKENS` (11), `SET_TOKEN_METADATA` (21) | Operator that manages token supply and metadata. |
+| **Treasury manager** | `SEND_PAYOUTS` (5), `USE_ALLOWANCE` (17), `ADD_ACCOUNTING_CONTEXTS` (20) | Operator that manages outflows from the project treasury. |
+| **Project admin** | `SET_PROJECT_URI` (7), `DEPLOY_ERC20` (8), `SET_CONTROLLER` (14), `SET_TERMINALS` (15), `SET_PRIMARY_TERMINAL` (16) | Broad administrative access without ROOT. |
+| **NFT manager** | `ADJUST_721_TIERS` (22), `SET_721_METADATA` (23), `MINT_721` (24), `SET_721_DISCOUNT_PERCENT` (25) | Full control over 721 tier configuration. |
+| **Cross-chain operator** | `DEPLOY_SUCKERS` (31), `MAP_SUCKER_TOKEN` (30), `SET_SUCKER_DEPRECATION` (33) | Manages cross-chain bridging lifecycle. |
+| **Launch bundle** | `LAUNCH_RULESETS` (3), `SET_TERMINALS` (15) | Both are required for `launchRulesetsFor` -- ID 3 alone is insufficient. |
+
 ## Integration Points
 
 | Dependency | Import | Used For |
@@ -125,7 +130,7 @@ N/A -- no structs or enums. All values are `uint8 internal constant`.
 - **SET_TERMINALS (ID 15) can break a project.** Replacing the terminal list without including the current primary terminal will remove it, breaking payments and cashouts until a new primary is set.
 - **LAUNCH_RULESETS (ID 3) requires both IDs 3 and 15.** The function enforces two separate permission checks because it configures terminals in addition to launching rulesets.
 - **Holder-scoped permissions.** IDs 4 (`CASH_OUT_TOKENS`), 11 (`BURN_TOKENS`), 12 (`CLAIM_TOKENS`), and 13 (`TRANSFER_CREDITS`) are checked against the **token holder**, not the project owner. This means a holder grants an operator permission to act on the holder's own tokens.
-- **SET_BUYBACK_HOOK (ID 28) mismatch.** The source comment says it guards `JBBuybackHookRegistry.setHookFor` and `lockHookFor`, but those functions actually check `SET_BUYBACK_POOL` (ID 27). The ID is still granted by `REVDeployer` as an operator permission.
+- **SET_BUYBACK_POOL (ID 27) vs SET_BUYBACK_HOOK (ID 28) — different scopes.** ID 27 guards pool configuration (`setPoolFor`, `initializePoolFor`). ID 28 guards hook selection (`setHookFor`, `lockHookFor`). `setTwapWindowOf` uses ID 26 (`SET_BUYBACK_TWAP`). Grant all three if the operator needs full buyback management.
 - **ADD_PRICE_FEED (ID 19) is checked on JBController, not JBPrices.** The permission gate is on `JBController.addPriceFeed`, which then calls `JBPrices.addPriceFeedFor` internally.
 - **uint8 range.** IDs are `uint8` (0--255) but the packed storage is `uint256`, so the system supports up to 256 permission bits. Currently 33 are defined (1--33).
 

package/STYLE_GUIDE.md

@@ -21,7 +21,7 @@ One contract/interface/struct/enum per file. Name the file after the type it con
 
 ```solidity
 // Contracts — pin to exact version
-pragma solidity 0.8.26;
+pragma solidity 0.8.28;
 
 // Interfaces, structs, enums — caret for forward compatibility
 pragma solidity ^0.8.0;
@@ -313,7 +313,7 @@ Standard config across all repos:
 
 ```toml
 [profile.default]
-solc = '0.8.26'
+solc = '0.8.28'
 evm_version = 'cancun'
 optimizer_runs = 200
 libs = ["node_modules", "lib"]

package/USER_JOURNEYS.md

@@ -1,11 +1,20 @@
 # User Journeys -- nana-permission-ids-v6
 
-Since this is a constants-only library with no runtime behavior, these journeys describe how the permission IDs are used by actors across the ecosystem. Each journey shows the constant's role in a concrete access control scenario.
+Since this is a constants-only library with no runtime behavior, these journeys describe how the permission IDs are used by actors across the ecosystem. Each journey shows the constant's role in a concrete access control scenario. All events referenced below are emitted by `JBPermissions` (in nana-core-v6), not by this library.
+
+---
 
 ## Journey 1: Grant an Operator Permission to Queue Rulesets
 
-**Actor:** Project owner granting delegated access to a trusted operator.
-**Goal:** Allow an operator to queue new rulesets for a project without transferring project ownership.
+**Entry point**: `JBPermissions.setPermissionsFor(address account, JBPermissionsData calldata permissionsData)`
+
+**Who can call**: The `account` itself, or an existing operator that holds `ROOT` for the same `(account, projectId)` -- provided the new permissions do not include `ROOT` and the `projectId` is not the wildcard (`0`).
+
+**Parameters**:
+- `account` -- The address granting permissions (the project owner in this scenario)
+- `permissionsData.operator` -- The address receiving permissions (the trusted operator)
+- `permissionsData.projectId` -- The project ID the permissions are scoped to (e.g. `5`)
+- `permissionsData.permissionIds` -- Array of `uint8` permission IDs to grant (e.g. `[JBPermissionIds.QUEUE_RULESETS]` which is ID 2)
 
 ### Steps
 
@@ -20,25 +29,36 @@ Since this is a constants-only library with no runtime behavior, these journeys
    );
    ```
 
-   - Sets bit 2 in `permissionsOf[operatorAddress][projectOwner][5]`
-
 2. **Operator calls `JBController.queueRulesetsOf(5, ...)`**
 
    - Controller calls `_requirePermissionFrom(projectOwner, 5, JBPermissionIds.QUEUE_RULESETS)`
    - `JBPermissions.hasPermission` checks: does `operatorAddress` have bit 2 set for `(projectOwner, projectId=5)`? Yes.
    - Operation proceeds.
 
-### What to verify
+**State changes**:
+1. `JBPermissions.permissionsOf[operatorAddress][projectOwner][5]` -- bit 2 set to 1 (packed uint256 bitmap)
+
+**Events**: `OperatorPermissionsSet(operator, account, projectId, permissionIds, packed, caller)` -- emitted by `JBPermissions`, not this library.
 
+**Edge cases**:
 - The operator can ONLY queue rulesets. They cannot send payouts, set terminals, or perform any other operation unless additional IDs are granted.
 - Granting `QUEUE_RULESETS` with `projectId = 0` (wildcard) would allow the operator to queue rulesets for ALL projects the owner controls.
+- `JBPermissions_NoZeroPermission()` -- reverts if permission ID 0 is included in the array.
+- `JBPermissions_PermissionIdOutOfBounds(permissionId)` -- reverts if any permission ID exceeds 255.
 
 ---
 
 ## Journey 2: ROOT Permission Grants Universal Access
 
-**Actor:** Project owner granting ROOT to a highly trusted multisig.
-**Goal:** Give a single operator full control over all project operations.
+**Entry point**: `JBPermissions.setPermissionsFor(address account, JBPermissionsData calldata permissionsData)`
+
+**Who can call**: Only the `account` itself can grant `ROOT`. An existing ROOT operator cannot grant ROOT to others (the function enforces this restriction explicitly).
+
+**Parameters**:
+- `account` -- The address granting ROOT (must be the caller)
+- `permissionsData.operator` -- The address receiving ROOT (e.g. a trusted multisig)
+- `permissionsData.projectId` -- Must be a specific project ID (not `0`)
+- `permissionsData.permissionIds` -- `[JBPermissionIds.ROOT]` (ID 1)
 
 ### Steps
 
@@ -53,26 +73,36 @@ Since this is a constants-only library with no runtime behavior, these journeys
    );
    ```
 
-   - Sets bit 1 in `permissionsOf[multisigAddress][projectOwner][5]`
-
 2. **Multisig calls any permissioned function for project 5**
 
    - Every `_requirePermissionFrom` check includes `includeRoot: true`
    - ROOT (bit 1) satisfies any permission check for `(projectOwner, projectId=5)`
    - The multisig can queue rulesets, send payouts, set terminals, mint tokens, etc.
 
-### What to verify
+**State changes**:
+1. `JBPermissions.permissionsOf[multisigAddress][projectOwner][5]` -- bit 1 set to 1
+
+**Events**: `OperatorPermissionsSet(operator, account, projectId, permissionIds, packed, caller)` -- emitted by `JBPermissions`, not this library.
 
-- ROOT cannot be granted with `projectId = 0`. `JBPermissions` reverts with `JBPermissions_CantSetRootPermissionForWildcardProject()`.
-- A ROOT operator can call `setPermissionsFor` on behalf of the account, but cannot grant ROOT to other operators or set wildcard permissions. This prevents permission escalation.
+**Edge cases**:
+- `JBPermissions_CantSetRootPermissionForWildcardProject()` -- reverts if ROOT is granted with `projectId = 0`.
+- `JBPermissions_Unauthorized(account, operator, projectId, permissionId)` -- reverts if a non-account caller (even a ROOT operator) tries to grant ROOT to another operator, or tries to set wildcard permissions.
 - ROOT is per-project. Having ROOT for project 5 does not grant access to project 6.
+- A ROOT operator can call `setPermissionsFor` on behalf of the account for non-ROOT, non-wildcard grants only. This prevents permission escalation.
 
 ---
 
 ## Journey 3: Token Holder Delegates Cashout Authority
 
-**Actor:** Token holder (not project owner) granting a bot permission to cash out tokens on their behalf.
-**Goal:** Allow automated cashout execution without exposing the holder's private key.
+**Entry point**: `JBPermissions.setPermissionsFor(address account, JBPermissionsData calldata permissionsData)`
+
+**Who can call**: The token holder (the `account`), or an existing ROOT operator for the holder on the relevant project.
+
+**Parameters**:
+- `account` -- The token holder granting permission (NOT the project owner)
+- `permissionsData.operator` -- The bot or delegate receiving cashout permission
+- `permissionsData.projectId` -- The project ID the tokens belong to (e.g. `5`)
+- `permissionsData.permissionIds` -- `[JBPermissionIds.CASH_OUT_TOKENS]` (ID 4)
 
 ### Steps
 
@@ -94,8 +124,12 @@ Since this is a constants-only library with no runtime behavior, these journeys
    - Terminal calls `_requirePermissionFrom(tokenHolder, 5, JBPermissionIds.CASH_OUT_TOKENS)`
    - Permission check passes for `botAddress` because it has `CASH_OUT_TOKENS` for `(tokenHolder, 5)`
 
-### What to verify
+**State changes**:
+1. `JBPermissions.permissionsOf[botAddress][tokenHolder][5]` -- bit 4 set to 1
+
+**Events**: `OperatorPermissionsSet(operator, account, projectId, permissionIds, packed, caller)` -- emitted by `JBPermissions`, not this library.
 
+**Edge cases**:
 - `CASH_OUT_TOKENS` (ID 4) is checked against the token holder, not the project owner. This is by design -- only the holder (or their delegates) can cash out the holder's tokens.
 - The project owner CANNOT cash out another holder's tokens (unless the holder explicitly grants them `CASH_OUT_TOKENS`).
 - The same holder-scoped pattern applies to `BURN_TOKENS` (11), `CLAIM_TOKENS` (12), and `TRANSFER_CREDITS` (13).
@@ -104,8 +138,13 @@ Since this is a constants-only library with no runtime behavior, these journeys
 
 ## Journey 4: SET_TERMINALS Can Break a Project
 
-**Actor:** Project owner (or delegate with SET_TERMINALS permission).
-**Goal:** Update the list of terminals for a project -- illustrating the risk documented in the source.
+**Entry point**: `JBDirectory.setTerminalsOf(uint256 projectId, IJBTerminal[] calldata terminals)`
+
+**Who can call**: The project owner, or an address with the owner's `SET_TERMINALS` (ID 15) permission for that project.
+
+**Parameters**:
+- `projectId` -- The project whose terminals are being updated
+- `terminals` -- The new complete list of terminals (replaces the entire existing list)
 
 ### Steps
 
@@ -122,8 +161,13 @@ Since this is a constants-only library with no runtime behavior, these journeys
    - All payouts via `sendPayoutsOf()` will fail
    - The project is effectively frozen until a new primary terminal is set
 
-### What to verify
+**State changes**:
+1. `JBDirectory._terminalsOf[projectId]` -- replaced with the new terminals array
+2. `JBDirectory._primaryTerminalOf[projectId][token]` -- may be implicitly cleared if the primary terminal is not in the new list
+
+**Events**: `SetTerminals(projectId, terminals, caller)` -- emitted by `JBDirectory` (in nana-core-v6), not this library.
 
+**Edge cases**:
 - Granting `SET_TERMINALS` to an untrusted operator is dangerous. The operator can remove all terminals, bricking the project.
 - `LAUNCH_RULESETS` (ID 3) also requires `SET_TERMINALS` (ID 15) because the launch function configures terminals. Granting only ID 3 without ID 15 will cause the launch to revert.
 - There is no undo mechanism. Once terminals are set, another `setTerminalsOf` call is needed to restore them.
@@ -132,8 +176,15 @@ Since this is a constants-only library with no runtime behavior, these journeys
 
 ## Journey 5: Locking a Buyback Hook or Router Terminal (Permanent Action)
 
-**Actor:** Project owner or delegate with SET_BUYBACK_HOOK or SET_ROUTER_TERMINAL permission.
-**Goal:** Illustrate the irreversible locking behavior gated by dual-purpose permission IDs.
+**Entry point (buyback hook)**:
+- `JBBuybackHookRegistry.setHookFor(uint256 projectId, IJBRulesetDataHook hook)` -- configures the hook
+- `JBBuybackHookRegistry.lockHookFor(uint256 projectId, IJBRulesetDataHook expectedHook)` -- permanently locks the configuration
+
+**Who can call**: The project owner, or an address with the owner's `SET_BUYBACK_HOOK` (ID 28) permission for that project. A single permission ID gates both operations.
+
+**Parameters**:
+- `projectId` -- The project whose buyback hook is being configured or locked
+- `hook` -- The buyback hook contract address (for `setHookFor` only)
 
 ### Steps (SET_BUYBACK_HOOK example)
 
@@ -142,13 +193,19 @@ Since this is a constants-only library with no runtime behavior, these journeys
    - Configures the buyback hook for project 5
    - This is a reversible operation (can be called again with a different hook)
 
-2. **Same operator calls `JBBuybackHookRegistry.lockHookFor(5)`**
+2. **Same operator calls `JBBuybackHookRegistry.lockHookFor(5, hookAddress)`**
 
+   - The `expectedHook` parameter is a race-condition guard: the call reverts with `JBBuybackHookRegistry_HookMismatch` if the on-chain hook differs from `expectedHook` at execution time
    - Permanently locks the hook configuration for project 5
    - No one can change the hook after locking -- not even the project owner
 
-### What to verify
+**State changes**:
+1. `JBBuybackHookRegistry._hookOf[projectId]` -- set to the hook address (step 1)
+2. `JBBuybackHookRegistry.hasLockedHook[projectId]` -- set to `true` (step 2, irreversible)
+
+**Events**: Events are emitted by `JBBuybackHookRegistry` (in nana-buyback-hook-v6), not this library.
 
+**Edge cases**:
 - A single permission ID (28 or 29) gates BOTH the "set" and "lock" operations. Granting the permission implicitly trusts the operator to potentially lock the configuration.
 - The locking is permanent (no unlock mechanism in the registry).
 - Project owners should only grant SET_BUYBACK_HOOK (28) or SET_ROUTER_TERMINAL (29) to operators they trust not to lock prematurely.
@@ -157,31 +214,87 @@ Since this is a constants-only library with no runtime behavior, these journeys
 
 ## Journey 6: Cross-Repo Permission Usage (nana-suckers)
 
-**Actor:** Project owner managing cross-chain infrastructure.
-**Goal:** Deploy suckers and manage their lifecycle using permission IDs 30-33.
+**Entry point**: Multiple functions across `JBSuckerRegistry` and `JBSucker`, each gated by a separate permission ID.
+
+**Who can call**: The project owner, or an address with the corresponding permission for that project. Each sucker permission is independent.
+
+**Parameters** (vary by operation):
+- `projectId` -- The project managing cross-chain infrastructure
+- `configurations` -- Sucker deployment configurations (for `deploySuckersFor`)
+- `map` -- A `JBTokenMapping` struct (for `mapToken`)
+- `tokens` -- Token addresses (`address[]`) for emergency recovery (for `enableEmergencyHatchFor`)
+- `timestamp` -- The timestamp after which the sucker is deprecated (for `setDeprecation`)
 
 ### Steps
 
-1. **Deploy suckers: `JBSuckerRegistry.deploySuckersFor(5, configs)`**
+1. **Deploy suckers: `JBSuckerRegistry.deploySuckersFor(5, salt, configurations)`**
    - Permission: `DEPLOY_SUCKERS` (ID 31)
    - Creates sucker contracts for cross-chain bridging
 
-2. **Map tokens: `JBSucker.mapToken(localToken, remoteToken)`**
+2. **Map tokens: `JBSucker.mapToken(map)`** where `map` is a `JBTokenMapping` struct
    - Permission: `MAP_SUCKER_TOKEN` (ID 30)
    - Maps a local ERC-20 to its remote chain counterpart
    - CAUTION: once the outbox merkle tree has entries, the mapping is immutable (can only be disabled, not remapped)
 
-3. **Enable emergency hatch: `JBSucker.enableEmergencyHatchFor(token)`**
+3. **Enable emergency hatch: `JBSucker.enableEmergencyHatchFor(tokens)`**
    - Permission: `SUCKER_SAFETY` (ID 32)
    - Allows recovery of stuck tokens via the emergency hatch
 
-4. **Deprecate sucker: `JBSucker.setDeprecation(newState)`**
+4. **Deprecate sucker: `JBSucker.setDeprecation(timestamp)`**
    - Permission: `SET_SUCKER_DEPRECATION` (ID 33)
-   - Moves the sucker through its lifecycle: ENABLED -> DEPRECATION_PENDING -> SENDING_DISABLED -> DEPRECATED
+   - The timestamp after which the sucker is deprecated.
+
+**State changes** (per step):
+1. `JBSuckerRegistry` -- deploys new sucker contracts, registers them for the project
+2. `JBSucker._remoteTokenFor[localToken]` -- set to the remote token mapping (immutable once outbox tree populated)
+3. `JBSucker._remoteTokenFor[token].enabled` -- set to `false` (bridging disabled for this token)
+4. `JBSucker._remoteTokenFor[token].emergencyHatch` -- set to `true`
+5. `JBSucker.deprecatedAfter` -- set to `timestamp` (the time after which the sucker is deprecated, or `0` to cancel a pending deprecation)
 
-### What to verify
+**Events**: Events are emitted by `JBSuckerRegistry` and `JBSucker` (in nana-suckers-v6), not this library.
 
+**Edge cases**:
 - Each sucker permission is independent. Having `DEPLOY_SUCKERS` does not grant `MAP_SUCKER_TOKEN` or `SUCKER_SAFETY`.
 - `MAP_SUCKER_TOKEN` is especially sensitive because token mappings become immutable once the outbox tree has entries.
 - `SUCKER_SAFETY` should be granted sparingly -- the emergency hatch is a last-resort recovery mechanism.
 - All four sucker permissions are checked against the project owner, not a token holder.
+
+---
+
+## Permission ID Reference
+
+| ID | Constant | Gated function(s) | Scope |
+|----|----------|-------------------|-------|
+| 1 | `ROOT` | All permissioned functions | Project owner |
+| 2 | `QUEUE_RULESETS` | `JBController.queueRulesetsOf` | Project owner |
+| 3 | `LAUNCH_RULESETS` | `JBController.launchRulesetsFor` | Project owner |
+| 4 | `CASH_OUT_TOKENS` | `JBMultiTerminal.cashOutTokensOf` | Token holder |
+| 5 | `SEND_PAYOUTS` | `JBMultiTerminal.sendPayoutsOf` | Project owner |
+| 6 | `MIGRATE_TERMINAL` | `JBMultiTerminal.migrateBalanceOf` | Project owner |
+| 7 | `SET_PROJECT_URI` | `JBController.setUriOf` | Project owner |
+| 8 | `DEPLOY_ERC20` | `JBController.deployERC20For` | Project owner |
+| 9 | `SET_TOKEN` | `JBController.setTokenFor` | Project owner |
+| 10 | `MINT_TOKENS` | `JBController.mintTokensOf` | Project owner |
+| 11 | `BURN_TOKENS` | `JBController.burnTokensOf` | Token holder |
+| 12 | `CLAIM_TOKENS` | `JBController.claimTokensFor` | Token holder |
+| 13 | `TRANSFER_CREDITS` | `JBController.transferCreditsFrom` | Token holder |
+| 14 | `SET_CONTROLLER` | `JBDirectory.setControllerOf` | Project owner |
+| 15 | `SET_TERMINALS` | `JBDirectory.setTerminalsOf` | Project owner |
+| 16 | `SET_PRIMARY_TERMINAL` | `JBDirectory.setPrimaryTerminalOf` | Project owner |
+| 17 | `USE_ALLOWANCE` | `JBMultiTerminal.useAllowanceOf` | Project owner |
+| 18 | `SET_SPLIT_GROUPS` | `JBController.setSplitGroupsOf` | Project owner |
+| 19 | `ADD_PRICE_FEED` | `JBController.addPriceFeedFor` | Project owner |
+| 20 | `ADD_ACCOUNTING_CONTEXTS` | `JBMultiTerminal.addAccountingContextsFor` | Project owner |
+| 21 | `SET_TOKEN_METADATA` | `JBController.setTokenMetadataOf` | Project owner |
+| 22 | `ADJUST_721_TIERS` | `JB721TiersHook.adjustTiers` | Project owner |
+| 23 | `SET_721_METADATA` | `JB721TiersHook.setMetadata` | Project owner |
+| 24 | `MINT_721` | `JB721TiersHook.mintFor` | Project owner |
+| 25 | `SET_721_DISCOUNT_PERCENT` | `JB721TiersHook.setDiscountPercentOf` | Project owner |
+| 26 | `SET_BUYBACK_TWAP` | `JBBuybackHook.setTwapWindowOf` | Project owner |
+| 27 | `SET_BUYBACK_POOL` | `JBBuybackHook.setPoolFor` | Project owner |
+| 28 | `SET_BUYBACK_HOOK` | `JBBuybackHookRegistry.setHookFor` + `lockHookFor` | Project owner |
+| 29 | `SET_ROUTER_TERMINAL` | `JBRouterTerminalRegistry.setTerminalFor` + `lockTerminalFor` | Project owner |
+| 30 | `MAP_SUCKER_TOKEN` | `JBSucker.mapToken` | Project owner |
+| 31 | `DEPLOY_SUCKERS` | `JBSuckerRegistry.deploySuckersFor` | Project owner |
+| 32 | `SUCKER_SAFETY` | `JBSucker.enableEmergencyHatchFor` | Project owner |
+| 33 | `SET_SUCKER_DEPRECATION` | `JBSucker.setDeprecation` | Project owner |

package/foundry.toml

@@ -1,5 +1,5 @@
 [profile.default]
-solc = '0.8.26'
+solc = '0.8.28'
 evm_version = 'cancun'
 optimizer_runs = 200
 libs = ["node_modules", "lib"]

package/package.json

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

package/src/JBPermissionIds.sol

@@ -28,7 +28,7 @@ library JBPermissionIds {
     uint8 internal constant SET_PRIMARY_TERMINAL = 16; // Permission to call `JBDirectory.setPrimaryTerminalOf`.
     uint8 internal constant USE_ALLOWANCE = 17; // Permission to call `JBMultiTerminal.useAllowanceOf`.
     uint8 internal constant SET_SPLIT_GROUPS = 18; // Permission to call `JBController.setSplitGroupsOf`.
-    uint8 internal constant ADD_PRICE_FEED = 19; // Permission to call `JBController.addPriceFeed`.
+    uint8 internal constant ADD_PRICE_FEED = 19; // Permission to call `JBController.addPriceFeedFor`.
     uint8 internal constant ADD_ACCOUNTING_CONTEXTS = 20; // Permission to call
     // `JBMultiTerminal.addAccountingContextsFor`.
     uint8 internal constant SET_TOKEN_METADATA = 21; // Permission to call