@bananapus/permission-ids-v6 0.0.9 → 0.0.10

package/ADMINISTRATION.md

@@ -32,9 +32,9 @@ All 33 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 | `SET_TOKEN_METADATA` | nana-core | `JBController.setMetadataOf` -- set a project token's name and symbol. |
+| 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. |

package/ARCHITECTURE.md

@@ -33,9 +33,9 @@ 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 | `SET_TOKEN_METADATA` | nana-core | `JBController.setMetadataOf` |
+| 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` |

package/AUDIT_INSTRUCTIONS.md

@@ -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

@@ -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

@@ -49,7 +49,7 @@ 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.setMetadataOf` | Set a project token's name and symbol. Checked against the project owner. |
+| 21 | `SET_TOKEN_METADATA` | `JBController.setTokenMetadataOf` | Set a project token's name and symbol. Checked against the project owner. |
 
 ### 721 Hook (IDs 22--25) -- [nana-721-hook-v6](https://github.com/Bananapus/nana-721-hook-v6)
 

package/RISKS.md

@@ -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-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
+- 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

@@ -58,7 +58,7 @@ 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.setMetadataOf` | Set a project token's name and symbol. 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
 
@@ -125,7 +125,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 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 33 are defined (1--33).
 

package/USER_JOURNEYS.md

@@ -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

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

package/src/JBPermissionIds.sol

@@ -28,11 +28,11 @@ 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.setMetadataOf`.
+    // `JBController.setTokenMetadataOf`.
 
     /* Used by `nana-721-hook`: https://github.com/Bananapus/nana-721-hook */
     uint8 internal constant ADJUST_721_TIERS = 22; // Permission to call `JB721TiersHook.adjustTiers`.