npm - @bananapus/permission-ids-v6 - Versions diffs - 0.0.8 → 0.0.10 - Mend

@bananapus/permission-ids-v6 0.0.8 → 0.0.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

package/ADMINISTRATION.md CHANGED Viewed

@@ -10,7 +10,7 @@ There are no ownable contracts, no upgrade mechanisms, and no mutable state. The
 ## Permission IDs
-All 32 defined permission IDs and what they control:
+All 33 defined permission IDs and what they control:
 | ID | Constant | Used By | What It Controls |
 |----|----------|---------|-----------------|
@@ -32,22 +32,23 @@ All 32 defined permission IDs and what they control:
 | 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. |
+| 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 | `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.
+| 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). |
+IDs 0 and 34-255 are unused. ID 0 is reserved and cannot be set. IDs 34-255 are available for future ecosystem extensions.
 ## ROOT Permission
@@ -88,8 +89,8 @@ 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.
+- **`SET_BUYBACK_HOOK` (28):** Can permanently lock the buyback hook configuration.
+- **`SET_ROUTER_TERMINAL` (29):** Can permanently lock the router terminal configuration.
 - **`MINT_TOKENS` (10):** Can inflate token supply (subject to ruleset allowing owner minting).
 ## Holder vs. Owner Permissions

package/ARCHITECTURE.md CHANGED Viewed

@@ -33,20 +33,21 @@ 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 | `JBPrices.addPriceFeedFor` |
+| 19 | `ADD_PRICE_FEED` | nana-core | `JBController.addPriceFeed` |
 | 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` |
+| 21 | `SET_TOKEN_METADATA` | nana-core | `JBController.setTokenMetadataOf` |
+| 22 | `ADJUST_721_TIERS` | nana-721-hook | `JB721TiersHook.adjustTiers` |
+| 23 | `SET_721_METADATA` | nana-721-hook | `JB721TiersHook.setMetadata` |
+| 24 | `MINT_721` | nana-721-hook | `JB721TiersHook.mintFor` |
+| 25 | `SET_721_DISCOUNT_PERCENT` | nana-721-hook | `JB721TiersHook.setDiscountPercentOf` |
+| 26 | `SET_BUYBACK_TWAP` | nana-buyback-hook | `JBBuybackHook.setTwapWindowOf` |
+| 27 | `SET_BUYBACK_POOL` | nana-buyback-hook | `JBBuybackHook.setPoolFor` |
+| 28 | `SET_BUYBACK_HOOK` | nana-buyback-hook | `JBBuybackHookRegistry.setHookFor` + `lockHookFor` |
+| 29 | `SET_ROUTER_TERMINAL` | nana-router-terminal | `JBRouterTerminalRegistry.setTerminalFor` + `lockTerminalFor` |
+| 30 | `MAP_SUCKER_TOKEN` | nana-suckers | `JBSucker.mapToken` |
+| 31 | `DEPLOY_SUCKERS` | nana-suckers | `JBSuckerRegistry.deploySuckersFor` |
+| 32 | `SUCKER_SAFETY` | nana-suckers | `JBSucker.enableEmergencyHatchFor` |
+| 33 | `SET_SUCKER_DEPRECATION` | nana-suckers | `JBSucker.setDeprecation` |
 ## Dependencies

package/AUDIT_INSTRUCTIONS.md ADDED Viewed

@@ -0,0 +1,149 @@
+# Audit Instructions -- nana-permission-ids-v6
+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.
+## Scope
+**In scope:**
+```
+src/JBPermissionIds.sol    # Constants library (~67 lines, 33 permission IDs)
+```
+**Out of scope:** All consuming contracts (nana-core, nana-721-hook, nana-buyback-hook, nana-router-terminal, nana-suckers, revnet-core, croptop-core). The constants library has no dependencies.
+## Architecture
+`JBPermissionIds` is a Solidity library containing 33 `uint8 internal constant` values numbered 1 through 33. These IDs are used with `JBPermissions.setPermissionsFor()` to grant scoped access to protocol functions. The permission system stores permissions as a 256-bit packed integer (`uint256`), with each bit corresponding to a permission ID.
+### Permission System Overview
+```
+permissionsOf[operator][account][projectId] => uint256 (one bit per permission ID)
+```
+- **Bit 0 (ID 0):** Reserved, cannot be set. `JBPermissions` reverts if bit 0 is included.
+- **Bit 1 (ID 1, ROOT):** Grants all permissions across all contracts. Cannot be granted for wildcard `projectId = 0`.
+- **Bits 2-33:** Individual permissions, each gating a specific function (or set of functions) in the ecosystem.
+- **Bits 34-255:** Unassigned, available for future extensions.
+### All Permission IDs
+| ID | Constant | Gated Function(s) | Checked Against |
+|----|----------|-------------------|-----------------|
+| 1 | `ROOT` | All permissions (implicit) | Project owner |
+| 2 | `QUEUE_RULESETS` | `JBController.queueRulesetsOf` | Project owner |
+| 3 | `LAUNCH_RULESETS` | `JBController.launchRulesetsFor` (also needs SET_TERMINALS) | 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` (WARNING: can remove primary terminal) | 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.addPriceFeed` (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 |
+| 23 | `SET_721_METADATA` | `JB721TiersHook.setMetadata` | Hook owner |
+| 24 | `MINT_721` | `JB721TiersHook.mintFor` | Hook owner |
+| 25 | `SET_721_DISCOUNT_PERCENT` | `JB721TiersHook.setDiscountPercentOf` | Hook 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 |
+## Priority Audit Areas
+### 1. ID Uniqueness (Highest Priority)
+Every permission ID must be unique. Two different constants with the same numeric value would cause one permission grant to silently authorize a different action. Verify:
+- All 33 constants have distinct values.
+- Values are sequential from 1 to 33 with no gaps and no duplicates.
+- No other file in the ecosystem defines additional permission ID constants that could collide with these.
+### 2. ID-to-Function Mapping Correctness
+Each constant's doc comment claims it gates a specific function. Verify against the actual source code of each consuming contract:
+- **nana-core-v6**: IDs 2-21 should match the `_requirePermissionFrom` calls in `JBController`, `JBMultiTerminal`, and `JBDirectory`.
+- **nana-721-hook-v6**: IDs 22-25 should match permission checks in `JB721TiersHook`.
+- **nana-buyback-hook-v6**: IDs 26-28 should match permission checks in `JBBuybackHook` and `JBBuybackHookRegistry`.
+- **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:
+- `CASH_OUT_TOKENS` (4) -- holder authorizes cashout of their tokens
+- `BURN_TOKENS` (11) -- holder authorizes burning their tokens
+- `CLAIM_TOKENS` (12) -- holder authorizes claiming their credits as ERC-20
+- `TRANSFER_CREDITS` (13) -- holder authorizes transferring their credit balance
+Verify that no consuming contract incorrectly checks these against the project owner. A confused check would mean the project owner could burn or cash out any holder's tokens (massive vulnerability).
+### 4. Dual-Purpose Permission IDs
+Two IDs intentionally gate both a "set" and a "lock" operation:
+- **SET_BUYBACK_HOOK (28)**: Gates both `setHookFor` (configurable) and `lockHookFor` (permanent). An operator with this permission can permanently lock the hook configuration.
+- **SET_ROUTER_TERMINAL (29)**: Gates both `setTerminalFor` (configurable) and `lockTerminalFor` (permanent). An operator with this permission can permanently lock the terminal configuration.
+Verify that project owners are aware of the locking implication when granting these permissions. The source code includes `@dev` documentation, but this is a significant trust escalation.
+### 5. ROOT Permission Safety
+ROOT (ID 1) is the superadmin permission. The `JBPermissions` contract implements critical safety rails:
+- ROOT cannot be granted for wildcard `projectId = 0` (would grant root across all projects)
+- A ROOT operator can call `setPermissionsFor` on behalf of the account but cannot grant ROOT to others
+- ROOT cannot be included when setting wildcard project permissions
+Verify these constraints are enforced in `JBPermissions`, not in this library (this library only defines the constant).
+### 6. SET_TERMINALS (ID 15) Risk
+The source comment warns: "Be careful - `SET_TERMINALS` can be used to remove the primary terminal." Additionally, `LAUNCH_RULESETS` (ID 3) requires both ID 3 AND ID 15 because the launch function configures terminals. Verify:
+- Granting `SET_TERMINALS` alone is sufficient to replace the entire terminal list, potentially breaking a project.
+- Granting `LAUNCH_RULESETS` without also granting `SET_TERMINALS` will cause `launchRulesetsFor` to revert (dual permission check).
+## Invariants to Verify
+1. **Uniqueness**: All 33 constants have unique values in the range [1, 33].
+2. **Completeness**: Every `_requirePermissionFrom` call in the ecosystem uses one of these constants (no magic numbers).
+3. **Type consistency**: All constants are `uint8`, matching the parameter type of `JBPermissions.hasPermission`.
+4. **No ID 0**: No constant has value 0 (reserved and forbidden by `JBPermissions`).
+5. **Sequential assignment**: IDs are assigned 1 through 33 with no gaps.
+## Testing Setup
+This is a constants-only library with no runtime behavior. There are no test files. Verification is done by cross-referencing the constants against consuming contracts.
+```bash
+cd nana-permission-ids-v6
+forge build  # Ensures the library compiles
+```
+To verify ID usage across the ecosystem:
+```bash
+# Search for permission ID usage in consuming repos
+grep -r "JBPermissionIds\." ../nana-core-v6/src/ ../nana-721-hook-v6/src/ ../nana-buyback-hook-v6/src/ ../nana-router-terminal-v6/src/ ../nana-suckers-v6/src/
+```
+Go break it.

package/CHANGE_LOG.md ADDED Viewed

@@ -0,0 +1,142 @@
+# nana-permission-ids-v6 Changelog (v5 → v6)
+This document describes all changes between `nana-permission-ids` (v5) and `nana-permission-ids-v6` (v6).
+---
+## 1. Breaking Changes
+### All numeric IDs shifted
+The insertion of `LAUNCH_RULESETS` at ID 3 pushed every subsequent permission ID up by one. Additional new permissions at the end of each section caused further shifts. **Any code that hardcodes numeric permission values will break.**
+| Permission | v5 ID | v6 ID |
+|---|---|---|
+| `ROOT` | 1 | 1 |
+| `QUEUE_RULESETS` | 2 | 2 |
+| `CASH_OUT_TOKENS` | 3 | 4 |
+| `SEND_PAYOUTS` | 4 | 5 |
+| `MIGRATE_TERMINAL` | 5 | 6 |
+| `SET_PROJECT_URI` | 6 | 7 |
+| `DEPLOY_ERC20` | 7 | 8 |
+| `SET_TOKEN` | 8 | 9 |
+| `MINT_TOKENS` | 9 | 10 |
+| `BURN_TOKENS` | 10 | 11 |
+| `CLAIM_TOKENS` | 11 | 12 |
+| `TRANSFER_CREDITS` | 12 | 13 |
+| `SET_CONTROLLER` | 13 | 14 |
+| `SET_TERMINALS` | 14 | 15 |
+| `SET_PRIMARY_TERMINAL` | 15 | 16 |
+| `USE_ALLOWANCE` | 16 | 17 |
+| `SET_SPLIT_GROUPS` | 17 | 18 |
+| `ADD_PRICE_FEED` | 18 | 19 |
+| `ADD_ACCOUNTING_CONTEXTS` | 19 | 20 |
+| `ADJUST_721_TIERS` | 20 | 22 |
+| `SET_721_METADATA` | 21 | 23 |
+| `MINT_721` | 22 | 24 |
+| `SET_721_DISCOUNT_PERCENT` | 23 | 25 |
+| `SET_BUYBACK_TWAP` | 24 | 26 |
+| `SET_BUYBACK_POOL` | 25 | 27 |
+| `MAP_SUCKER_TOKEN` | 28 | 30 |
+| `DEPLOY_SUCKERS` | 29 | 31 |
+| `SUCKER_SAFETY` | 30 | 32 |
+### `QUEUE_RULESETS` split into two permissions
+In v5, `QUEUE_RULESETS` (2) granted permission to call both `JBController.queueRulesetsOf` and `JBController.launchRulesetsFor`. In v6, these are separate:
+- `QUEUE_RULESETS` (2) -- only `JBController.queueRulesetsOf`
+- `LAUNCH_RULESETS` (3) -- only `JBController.launchRulesetsFor`
+### `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:
+- `SUCKER_SAFETY` (32) -- only `JBSucker.enableEmergencyHatchFor`
+- `SET_SUCKER_DEPRECATION` (33) -- only `JBSucker.setDeprecation`
+### Swap terminal permissions removed
+The following permissions from `nana-swap-terminal` no longer exist in v6:
+| Removed | v5 ID | Notes |
+|---|---|---|
+| `ADD_SWAP_TERMINAL_POOL` | 26 | Was for `JBSwapTerminal.addDefaultPool` |
+| `ADD_SWAP_TERMINAL_TWAP_PARAMS` | 27 | Was for `JBSwapTerminal.addTwapParamsFor` |
+### Contract prefix rename (suckers)
+Sucker contract references changed from `BP*` to `JB*`:
+- `BPSucker` → `JBSucker`
+- `BPSuckerRegistry` → `JBSuckerRegistry`
+### `SET_BUYBACK_TWAP` comment narrowed
+In v5, the comment stated this gates both `JBBuybackHook.setTwapWindowOf` and `JBBuybackHook.setTwapSlippageToleranceOf`. In v6, the comment only mentions `JBBuybackHook.setTwapWindowOf`.
+---
+## 2. New Features
+### `LAUNCH_RULESETS` (3)
+New permission split from `QUEUE_RULESETS`. Gates `JBController.launchRulesetsFor` independently.
+### `SET_TOKEN_METADATA` (21)
+New core permission. Gates `JBController.setMetadataOf` for setting project token metadata.
+### `SET_BUYBACK_HOOK` (28)
+New buyback hook permission. Gates both `JBBuybackHookRegistry.setHookFor` and `JBBuybackHookRegistry.lockHookFor`. Note: granting this permission allows the operator to permanently lock the hook configuration.
+### `SET_ROUTER_TERMINAL` (29)
+New router terminal permission. Gates both `JBRouterTerminalRegistry.setTerminalFor` and `JBRouterTerminalRegistry.lockTerminalFor`. Note: granting this permission allows the operator to permanently lock the terminal configuration.
+### `SET_SUCKER_DEPRECATION` (33)
+New permission split from `SUCKER_SAFETY`. Gates `JBSucker.setDeprecation` independently.
+---
+## 3. Migration Table
+| v5 Name | v5 ID | v6 Name | v6 ID | Change |
+|---|---|---|---|---|
+| `ROOT` | 1 | `ROOT` | 1 | Unchanged |
+| `QUEUE_RULESETS` | 2 | `QUEUE_RULESETS` | 2 | Narrowed (no longer includes launch) |
+| -- | -- | `LAUNCH_RULESETS` | 3 | **New** (split from `QUEUE_RULESETS`) |
+| `CASH_OUT_TOKENS` | 3 | `CASH_OUT_TOKENS` | 4 | ID changed |
+| `SEND_PAYOUTS` | 4 | `SEND_PAYOUTS` | 5 | ID changed |
+| `MIGRATE_TERMINAL` | 5 | `MIGRATE_TERMINAL` | 6 | ID changed |
+| `SET_PROJECT_URI` | 6 | `SET_PROJECT_URI` | 7 | ID changed |
+| `DEPLOY_ERC20` | 7 | `DEPLOY_ERC20` | 8 | ID changed |
+| `SET_TOKEN` | 8 | `SET_TOKEN` | 9 | ID changed |
+| `MINT_TOKENS` | 9 | `MINT_TOKENS` | 10 | ID changed |
+| `BURN_TOKENS` | 10 | `BURN_TOKENS` | 11 | ID changed |
+| `CLAIM_TOKENS` | 11 | `CLAIM_TOKENS` | 12 | ID changed |
+| `TRANSFER_CREDITS` | 12 | `TRANSFER_CREDITS` | 13 | ID changed |
+| `SET_CONTROLLER` | 13 | `SET_CONTROLLER` | 14 | ID changed |
+| `SET_TERMINALS` | 14 | `SET_TERMINALS` | 15 | ID changed |
+| `SET_PRIMARY_TERMINAL` | 15 | `SET_PRIMARY_TERMINAL` | 16 | ID changed |
+| `USE_ALLOWANCE` | 16 | `USE_ALLOWANCE` | 17 | ID changed |
+| `SET_SPLIT_GROUPS` | 17 | `SET_SPLIT_GROUPS` | 18 | ID changed |
+| `ADD_PRICE_FEED` | 18 | `ADD_PRICE_FEED` | 19 | ID changed |
+| `ADD_ACCOUNTING_CONTEXTS` | 19 | `ADD_ACCOUNTING_CONTEXTS` | 20 | ID changed |
+| -- | -- | `SET_TOKEN_METADATA` | 21 | **New** |
+| `ADJUST_721_TIERS` | 20 | `ADJUST_721_TIERS` | 22 | ID changed |
+| `SET_721_METADATA` | 21 | `SET_721_METADATA` | 23 | ID changed |
+| `MINT_721` | 22 | `MINT_721` | 24 | ID changed |
+| `SET_721_DISCOUNT_PERCENT` | 23 | `SET_721_DISCOUNT_PERCENT` | 25 | ID changed |
+| `SET_BUYBACK_TWAP` | 24 | `SET_BUYBACK_TWAP` | 26 | ID changed, comment narrowed |
+| `SET_BUYBACK_POOL` | 25 | `SET_BUYBACK_POOL` | 27 | ID changed |
+| `ADD_SWAP_TERMINAL_POOL` | 26 | -- | -- | **Removed** |
+| `ADD_SWAP_TERMINAL_TWAP_PARAMS` | 27 | -- | -- | **Removed** |
+| -- | -- | `SET_BUYBACK_HOOK` | 28 | **New** |
+| -- | -- | `SET_ROUTER_TERMINAL` | 29 | **New** |
+| `MAP_SUCKER_TOKEN` | 28 | `MAP_SUCKER_TOKEN` | 30 | ID changed, `BPSucker` → `JBSucker` |
+| `DEPLOY_SUCKERS` | 29 | `DEPLOY_SUCKERS` | 31 | ID changed, `BPSuckerRegistry` → `JBSuckerRegistry` |
+| `SUCKER_SAFETY` | 30 | `SUCKER_SAFETY` | 32 | ID changed, narrowed (no longer includes deprecation) |
+| -- | -- | `SET_SUCKER_DEPRECATION` | 33 | **New** (split from `SUCKER_SAFETY`) |

package/README.md CHANGED Viewed

@@ -1,6 +1,6 @@
 # Juicebox Permission IDs
-The single source of truth for access control across the Juicebox V6 ecosystem. This library defines 32 `uint8` constants -- one for each permission ID used with [`JBPermissions`](https://github.com/Bananapus/nana-core-v6/blob/main/src/JBPermissions.sol) -- ensuring every contract references the same IDs.
+The single source of truth for access control across the Juicebox V6 ecosystem. This library defines 33 `uint8` constants -- one for each permission ID used with [`JBPermissions`](https://github.com/Bananapus/nana-core-v6/blob/main/src/JBPermissions.sol) -- ensuring every contract references the same IDs.
 ## How permissions work
@@ -16,7 +16,7 @@ permissionsOf[operator][account][projectId] => uint256 (packed bits)
 | Contract | Description |
 |----------|-------------|
-| `JBPermissionIds` | Solidity library with 32 `uint8 internal constant` permission IDs (values 1--32). No state, no functions, no dependencies. Pragma `^0.8.0` for maximum compatibility. |
+| `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. |
 ## All permission IDs
@@ -26,7 +26,7 @@ permissionsOf[operator][account][projectId] => uint256 (packed bits)
 |----|------|-------------|
 | 1 | `ROOT` | Grants **all** permissions across every contract. An operator with ROOT can call any permissioned function on behalf of the account. Must be granted with extreme care. See [Gotchas](#gotchas) for restrictions. |
-### Core (IDs 2--20) -- [nana-core-v6](https://github.com/Bananapus/nana-core-v6)
+### Core (IDs 2--21) -- [nana-core-v6](https://github.com/Bananapus/nana-core-v6)
 | ID | Name | Checked in | Description |
 |----|------|------------|-------------|
@@ -49,38 +49,39 @@ permissionsOf[operator][account][projectId] => uint256 (packed bits)
 | 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`. |
 | 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. |
-### 721 Hook (IDs 21--24) -- [nana-721-hook-v6](https://github.com/Bananapus/nana-721-hook-v6)
+### 721 Hook (IDs 22--25) -- [nana-721-hook-v6](https://github.com/Bananapus/nana-721-hook-v6)
 | ID | Name | Checked in | Description |
 |----|------|------------|-------------|
-| 21 | `ADJUST_721_TIERS` | `JB721TiersHook.adjustTiers` | Add or remove NFT tiers. Also used by `CTPublisher` and `CTProjectOwner` in croptop-core-v6. |
-| 22 | `SET_721_METADATA` | `JB721TiersHook.setMetadata` | Set the metadata (base URI, contract URI, token URI resolver) for a 721 hook. |
-| 23 | `MINT_721` | `JB721TiersHook.mintFor` | Manually mint NFTs from specific tiers to a beneficiary. |
-| 24 | `SET_721_DISCOUNT_PERCENT` | `JB721TiersHook.setDiscountPercentOf` | Set the discount percent for one or more NFT tiers. |
+| 22 | `ADJUST_721_TIERS` | `JB721TiersHook.adjustTiers` | Add or remove NFT tiers. Also used by `CTPublisher` and `CTProjectOwner` in croptop-core-v6. |
+| 23 | `SET_721_METADATA` | `JB721TiersHook.setMetadata` | Set the metadata (base URI, contract URI, token URI resolver) for a 721 hook. |
+| 24 | `MINT_721` | `JB721TiersHook.mintFor` | Manually mint NFTs from specific tiers to a beneficiary. |
+| 25 | `SET_721_DISCOUNT_PERCENT` | `JB721TiersHook.setDiscountPercentOf` | Set the discount percent for one or more NFT tiers. |
-### Buyback Hook (IDs 25--27) -- [nana-buyback-hook-v6](https://github.com/Bananapus/nana-buyback-hook-v6)
+### Buyback Hook (IDs 26--28) -- [nana-buyback-hook-v6](https://github.com/Bananapus/nana-buyback-hook-v6)
 | ID | Name | Checked in | Description |
 |----|------|------------|-------------|
-| 25 | `SET_BUYBACK_TWAP` | `JBBuybackHook.setTwapWindowOf` | Set the TWAP (time-weighted average price) oracle window for a project's buyback hook. |
-| 26 | `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`. |
-| 27 | `SET_BUYBACK_HOOK` | *Reserved / revnet-core-v6* | Defined in `JBPermissionIds` for `JBBuybackHookRegistry.setHookFor` and `lockHookFor`, but the registry currently checks `SET_BUYBACK_POOL` (ID 26) for those functions. Used by `REVDeployer` in revnet-core-v6 as an operator permission grant. |
+| 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. |
-### Router Terminal (ID 28) -- [nana-router-terminal-v6](https://github.com/Bananapus/nana-router-terminal-v6)
+### Router Terminal (ID 29) -- [nana-router-terminal-v6](https://github.com/Bananapus/nana-router-terminal-v6)
 | ID | Name | Checked in | Description |
 |----|------|------------|-------------|
-| 28 | `SET_ROUTER_TERMINAL` | `JBRouterTerminalRegistry.setTerminalFor`, `JBRouterTerminalRegistry.lockTerminalFor` | Set or lock the router terminal for a project. |
+| 29 | `SET_ROUTER_TERMINAL` | `JBRouterTerminalRegistry.setTerminalFor`, `JBRouterTerminalRegistry.lockTerminalFor` | Set or lock the router terminal for a project. |
-### Suckers / Omnichain (IDs 29--32) -- [nana-suckers-v6](https://github.com/Bananapus/nana-suckers-v6)
+### Suckers / Omnichain (IDs 30--33) -- [nana-suckers-v6](https://github.com/Bananapus/nana-suckers-v6)
 | ID | Name | Checked in | Description |
 |----|------|------------|-------------|
-| 29 | `MAP_SUCKER_TOKEN` | `JBSucker.mapToken` | Map an ERC-20 token to its remote chain counterpart in a sucker. Mapping is immutable once the outbox tree has entries. |
-| 30 | `DEPLOY_SUCKERS` | `JBSuckerRegistry.deploySuckersFor` | Deploy new sucker contracts for a project. Also checked by `JBOmnichainDeployer` and `CTDeployer`. |
-| 31 | `SUCKER_SAFETY` | `JBSucker.enableEmergencyHatchFor` | Enable the emergency hatch for a sucker, allowing the project owner to recover stuck tokens. |
-| 32 | `SET_SUCKER_DEPRECATION` | `JBSucker.setDeprecation` | Set the deprecation status of a sucker (ENABLED, DEPRECATION_PENDING, SENDING_DISABLED, DEPRECATED). |
+| 30 | `MAP_SUCKER_TOKEN` | `JBSucker.mapToken` | Map an ERC-20 token to its remote chain counterpart in a sucker. Mapping is immutable once the outbox tree has entries. |
+| 31 | `DEPLOY_SUCKERS` | `JBSuckerRegistry.deploySuckersFor` | Deploy new sucker contracts for a project. Also checked by `JBOmnichainDeployer` and `CTDeployer`. |
+| 32 | `SUCKER_SAFETY` | `JBSucker.enableEmergencyHatchFor` | Enable the emergency hatch for a sucker, allowing the project owner to recover stuck tokens. |
+| 33 | `SET_SUCKER_DEPRECATION` | `JBSucker.setDeprecation` | Set the deprecation status of a sucker (ENABLED, DEPRECATION_PENDING, SENDING_DISABLED, DEPRECATED). |
 ## Gotchas
@@ -92,7 +93,7 @@ permissionsOf[operator][account][projectId] => uint256 (packed bits)
 - **SET_TERMINALS can remove the primary terminal.** The source code warns about this. Replacing the terminal list can drop the primary terminal, breaking payments and cashouts.
 - **LAUNCH_RULESETS requires SET_TERMINALS.** `launchRulesetsFor` enforces both `LAUNCH_RULESETS` and `SET_TERMINALS` because it configures terminals as part of the launch.
 - **Holder vs. owner permissions.** Most permissions are checked against the project owner, but `CASH_OUT_TOKENS`, `BURN_TOKENS`, `CLAIM_TOKENS`, and `TRANSFER_CREDITS` are checked against the **token holder**. This means a holder can grant an operator permission to cash out or burn their own tokens.
-- **The uint8 type limits IDs to 0--255.** Currently 32 are defined (1--32), leaving room for future extensions.
+- **The uint8 type limits IDs to 0--255.** Currently 33 are defined (1--33), leaving room for future extensions.
 ## Install

package/RISKS.md CHANGED Viewed

@@ -1,21 +1,18 @@
-# nana-permission-ids-v6 — Risks
+# RISKS.md -- nana-permission-ids-v6
-## Trust Assumptions
+Constants-only library defining permission ID values used throughout the Bananapus ecosystem. Contains no logic, no state, and no external calls.
-This is a constants-only library with no runtime behavior. The risk surface is limited to the correctness of the ID assignments.
+## 1. Known Risks
-## Known Risks
+- **ROOT permission (ID 1).** ROOT grants all permissions across every contract. Any address granted ROOT can perform any permissioned operation on any project. Should never be granted to untrusted addresses.
+- **SET_BUYBACK_HOOK includes lock (ID 28).** Gates both `setHookFor` and `lockHookFor`. An operator with this permission can permanently lock the buyback hook configuration.
+- **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.
-| 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 |
+## 2. Design Notes
-## 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
+- 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.
+- This library has zero dependencies -- it is the leaf of the dependency graph.

package/SKILLS.md CHANGED Viewed

@@ -8,7 +8,7 @@ Defines all `uint8` permission ID constants used across the Juicebox V6 ecosyste
 | Contract | Role |
 |----------|------|
-| `JBPermissionIds` | Constants-only library. 32 `uint8 internal constant` values (1--32). Pragma `^0.8.0` for maximum compatibility across all Juicebox contracts. |
+| `JBPermissionIds` | Constants-only library. 33 `uint8 internal constant` values (1--33). Pragma `^0.8.0` for maximum compatibility across all Juicebox contracts. |
 ## Key Functions
@@ -58,38 +58,39 @@ When a permissioned function is called, the contract checks whether the caller e
 | 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. |
 | 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. |
 ### nana-721-hook-v6
 | ID | Name | Checked in | Permission scope |
 |----|------|------------|-----------------|
-| 21 | `ADJUST_721_TIERS` | `JB721TiersHook.adjustTiers` | Add or remove NFT tiers. Checked against `owner()` (the project's controller). Also used by `CTPublisher`, `CTProjectOwner`, and `REVDeployer`. |
-| 22 | `SET_721_METADATA` | `JB721TiersHook.setMetadata` | Set base URI, contract URI, or token URI resolver. Checked against `owner()`. |
-| 23 | `MINT_721` | `JB721TiersHook.mintFor` | Manually mint NFTs from specific tiers. Checked against `owner()`. |
-| 24 | `SET_721_DISCOUNT_PERCENT` | `JB721TiersHook.setDiscountPercentOf` | Set the discount percent for NFT tiers. Checked against `owner()`. Called twice in the function for two separate code paths. |
+| 22 | `ADJUST_721_TIERS` | `JB721TiersHook.adjustTiers` | Add or remove NFT tiers. Checked against `owner()` (the project's controller). Also used by `CTPublisher`, `CTProjectOwner`, and `REVDeployer`. |
+| 23 | `SET_721_METADATA` | `JB721TiersHook.setMetadata` | Set base URI, contract URI, or token URI resolver. Checked against `owner()`. |
+| 24 | `MINT_721` | `JB721TiersHook.mintFor` | Manually mint NFTs from specific tiers. Checked against `owner()`. |
+| 25 | `SET_721_DISCOUNT_PERCENT` | `JB721TiersHook.setDiscountPercentOf` | Set the discount percent for NFT tiers. Checked against `owner()`. Called twice in the function for two separate code paths. |
 ### nana-buyback-hook-v6
 | ID | Name | Checked in | Permission scope |
 |----|------|------------|-----------------|
-| 25 | `SET_BUYBACK_TWAP` | `JBBuybackHook.setTwapWindowOf` | Set the TWAP oracle window duration. Checked against project owner. |
-| 26 | `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. |
-| 27 | `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 26) for those functions. Referenced by `REVDeployer` in revnet-core-v6 as an operator permission grant. |
+| 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. |
 ### nana-router-terminal-v6
 | ID | Name | Checked in | Permission scope |
 |----|------|------------|-----------------|
-| 28 | `SET_ROUTER_TERMINAL` | `JBRouterTerminalRegistry.setTerminalFor`, `JBRouterTerminalRegistry.lockTerminalFor` | Set or lock the router terminal for a project. Checked against project owner. |
+| 29 | `SET_ROUTER_TERMINAL` | `JBRouterTerminalRegistry.setTerminalFor`, `JBRouterTerminalRegistry.lockTerminalFor` | Set or lock the router terminal for a project. Checked against project owner. |
 ### nana-suckers-v6
 | ID | Name | Checked in | Permission scope |
 |----|------|------------|-----------------|
-| 29 | `MAP_SUCKER_TOKEN` | `JBSucker.mapToken` | Map an ERC-20 token to its remote chain counterpart. Immutable once the outbox merkle tree has entries. Checked against project owner. |
-| 30 | `DEPLOY_SUCKERS` | `JBSuckerRegistry.deploySuckersFor` | Deploy sucker contracts for cross-chain bridging. Checked against project owner. Also checked by `JBOmnichainDeployer` and `CTDeployer`. |
-| 31 | `SUCKER_SAFETY` | `JBSucker.enableEmergencyHatchFor` | Enable the emergency hatch to recover stuck tokens. Checked against project owner. |
-| 32 | `SET_SUCKER_DEPRECATION` | `JBSucker.setDeprecation` | Move a sucker through the deprecation lifecycle (ENABLED -> DEPRECATION_PENDING -> SENDING_DISABLED -> DEPRECATED). Checked against project owner. |
+| 30 | `MAP_SUCKER_TOKEN` | `JBSucker.mapToken` | Map an ERC-20 token to its remote chain counterpart. Immutable once the outbox merkle tree has entries. Checked against project owner. |
+| 31 | `DEPLOY_SUCKERS` | `JBSuckerRegistry.deploySuckersFor` | Deploy sucker contracts for cross-chain bridging. Checked against project owner. Also checked by `JBOmnichainDeployer` and `CTDeployer`. |
+| 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. |
 ## Integration Points
@@ -124,9 +125,9 @@ 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 27) mismatch.** The source comment says it guards `JBBuybackHookRegistry.setHookFor` and `lockHookFor`, but those functions actually check `SET_BUYBACK_POOL` (ID 26). The ID is still granted by `REVDeployer` as an operator permission.
+- **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.
 - **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 32 are defined (1--32).
+- **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).
 ## Example Integration

package/USER_JOURNEYS.md ADDED Viewed

@@ -0,0 +1,187 @@
+# 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.
+## 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.
+### Steps
+1. **Project owner calls `JBPermissions.setPermissionsFor`**
+   ```solidity
+   uint8[] memory ids = new uint8[](1);
+   ids[0] = JBPermissionIds.QUEUE_RULESETS; // ID 2
+   permissions.setPermissionsFor(
+       projectOwner,
+       JBPermissionsData({operator: operatorAddress, projectId: 5, permissionIds: ids})
+   );
+   ```
+   - 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
+- 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.
+---
+## 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.
+### Steps
+1. **Project owner calls `JBPermissions.setPermissionsFor`**
+   ```solidity
+   uint8[] memory ids = new uint8[](1);
+   ids[0] = JBPermissionIds.ROOT; // ID 1
+   permissions.setPermissionsFor(
+       projectOwner,
+       JBPermissionsData({operator: multisigAddress, projectId: 5, permissionIds: ids})
+   );
+   ```
+   - 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
+- 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.
+- ROOT is per-project. Having ROOT for project 5 does not grant access to project 6.
+---
+## 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.
+### Steps
+1. **Token holder calls `JBPermissions.setPermissionsFor`**
+   ```solidity
+   uint8[] memory ids = new uint8[](1);
+   ids[0] = JBPermissionIds.CASH_OUT_TOKENS; // ID 4
+   permissions.setPermissionsFor(
+       tokenHolder,
+       JBPermissionsData({operator: botAddress, projectId: 5, permissionIds: ids})
+   );
+   ```
+   - Note: the `account` is the **token holder**, not the project owner
+2. **Bot calls `JBMultiTerminal.cashOutTokensOf(tokenHolder, 5, ...)`**
+   - 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
+- `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).
+---
+## 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.
+### Steps
+1. **Operator calls `JBDirectory.setTerminalsOf(5, newTerminals)`**
+   - Permission check: `_requirePermissionFrom(projectOwner, 5, JBPermissionIds.SET_TERMINALS)` (ID 15)
+   - The `newTerminals` array replaces the ENTIRE terminal list
+2. **If the new list omits the current primary terminal:**
+   - The primary terminal is removed from the project
+   - All payments to the project via `pay()` will fail (no terminal to receive them)
+   - All cashouts via `cashOutTokensOf()` will fail
+   - All payouts via `sendPayoutsOf()` will fail
+   - The project is effectively frozen until a new primary terminal is set
+### What to verify
+- 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.
+---
+## 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.
+### Steps (SET_BUYBACK_HOOK example)
+1. **Operator with SET_BUYBACK_HOOK (ID 28) calls `JBBuybackHookRegistry.setHookFor(5, hookAddress)`**
+   - 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)`**
+   - Permanently locks the hook configuration for project 5
+   - No one can change the hook after locking -- not even the project owner
+### What to verify
+- 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.
+---
+## 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.
+### Steps
+1. **Deploy suckers: `JBSuckerRegistry.deploySuckersFor(5, configs)`**
+   - Permission: `DEPLOY_SUCKERS` (ID 31)
+   - Creates sucker contracts for cross-chain bridging
+2. **Map tokens: `JBSucker.mapToken(localToken, remoteToken)`**
+   - 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)`**
+   - Permission: `SUCKER_SAFETY` (ID 32)
+   - Allows recovery of stuck tokens via the emergency hatch
+4. **Deprecate sucker: `JBSucker.setDeprecation(newState)`**
+   - Permission: `SET_SUCKER_DEPRECATION` (ID 33)
+   - Moves the sucker through its lifecycle: ENABLED -> DEPRECATION_PENDING -> SENDING_DISABLED -> DEPRECATED
+### What to verify
+- 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.

package/package.json CHANGED Viewed

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

package/src/JBPermissionIds.sol CHANGED Viewed

@@ -28,24 +28,26 @@ 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 `JBPrices.addPriceFeedFor`.
+    uint8 internal constant ADD_PRICE_FEED = 19; // Permission to call `JBController.addPriceFeed`.
     uint8 internal constant ADD_ACCOUNTING_CONTEXTS = 20; // Permission to call
     // `JBMultiTerminal.addAccountingContextsFor`.
+    uint8 internal constant SET_TOKEN_METADATA = 21; // Permission to call
+    // `JBController.setTokenMetadataOf`.
     /* Used by `nana-721-hook`: https://github.com/Bananapus/nana-721-hook */
-    uint8 internal constant ADJUST_721_TIERS = 21; // Permission to call `JB721TiersHook.adjustTiers`.
-    uint8 internal constant SET_721_METADATA = 22; // Permission to call `JB721TiersHook.setMetadata`.
-    uint8 internal constant MINT_721 = 23; // Permission to call `JB721TiersHook.mintFor`.
-    uint8 internal constant SET_721_DISCOUNT_PERCENT = 24; // Permission to call `JB721TiersHook.setDiscountPercentOf`.
+    uint8 internal constant ADJUST_721_TIERS = 22; // Permission to call `JB721TiersHook.adjustTiers`.
+    uint8 internal constant SET_721_METADATA = 23; // Permission to call `JB721TiersHook.setMetadata`.
+    uint8 internal constant MINT_721 = 24; // Permission to call `JB721TiersHook.mintFor`.
+    uint8 internal constant SET_721_DISCOUNT_PERCENT = 25; // Permission to call `JB721TiersHook.setDiscountPercentOf`.
     /* Used by `nana-buyback-hook`: https://github.com/Bananapus/nana-buyback-hook */
-    uint8 internal constant SET_BUYBACK_TWAP = 25; // Permission to call `JBBuybackHook.setTwapWindowOf`.
-    uint8 internal constant SET_BUYBACK_POOL = 26; // Permission to call `JBBuybackHook.setPoolFor`.
+    uint8 internal constant SET_BUYBACK_TWAP = 26; // Permission to call `JBBuybackHook.setTwapWindowOf`.
+    uint8 internal constant SET_BUYBACK_POOL = 27; // Permission to call `JBBuybackHook.setPoolFor`.
     /// @dev This single ID intentionally gates both setting and locking the buyback hook as a simplification.
     /// Granting this permission allows the operator to call both `JBBuybackHookRegistry.setHookFor` (to configure the
     /// hook) and `JBBuybackHookRegistry.lockHookFor` (to permanently lock the hook configuration). Project owners
     /// should be aware that an operator with this permission can lock the hook, preventing future changes.
-    uint8 internal constant SET_BUYBACK_HOOK = 27; // Permission to call `JBBuybackHookRegistry.setHookFor` and
+    uint8 internal constant SET_BUYBACK_HOOK = 28; // Permission to call `JBBuybackHookRegistry.setHookFor` and
     // `JBBuybackHookRegistry.lockHookFor`.
     /* Used by `nana-router-terminal`: https://github.com/Bananapus/nana-router-terminal-v6 */
@@ -54,12 +56,12 @@ library JBPermissionIds {
     /// configure the terminal) and `JBRouterTerminalRegistry.lockTerminalFor` (to permanently lock the terminal
     /// configuration). Project owners should be aware that an operator with this permission can lock the terminal,
     /// preventing future changes.
-    uint8 internal constant SET_ROUTER_TERMINAL = 28; // Permission to call
+    uint8 internal constant SET_ROUTER_TERMINAL = 29; // Permission to call
     // `JBRouterTerminalRegistry.setTerminalFor` and `JBRouterTerminalRegistry.lockTerminalFor`.
     /* Used by `nana-suckers`: https://github.com/Bananapus/nana-suckers */
-    uint8 internal constant MAP_SUCKER_TOKEN = 29; // Permission to call `JBSucker.mapToken`.
-    uint8 internal constant DEPLOY_SUCKERS = 30; // Permission to call `JBSuckerRegistry.deploySuckersFor`.
-    uint8 internal constant SUCKER_SAFETY = 31; // Permission to call `JBSucker.enableEmergencyHatchFor`.
-    uint8 internal constant SET_SUCKER_DEPRECATION = 32; // Permission to call `JBSucker.setDeprecation`.
+    uint8 internal constant MAP_SUCKER_TOKEN = 30; // Permission to call `JBSucker.mapToken`.
+    uint8 internal constant DEPLOY_SUCKERS = 31; // Permission to call `JBSuckerRegistry.deploySuckersFor`.
+    uint8 internal constant SUCKER_SAFETY = 32; // Permission to call `JBSucker.enableEmergencyHatchFor`.
+    uint8 internal constant SET_SUCKER_DEPRECATION = 33; // Permission to call `JBSucker.setDeprecation`.
 }