npm - @bananapus/permission-ids-v6 - Versions diffs - 0.0.15 → 0.0.16 - Mend

@bananapus/permission-ids-v6 0.0.15 → 0.0.16

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 (13) hide show

package/ADMINISTRATION.md CHANGED Viewed

@@ -2,6 +2,31 @@
 Admin privileges and their scope in nana-permission-ids-v6.
+## At A Glance
+| Item | Details |
+|------|---------|
+| Scope | Reference library for the permission IDs consumed across the Juicebox V6 ecosystem. No contract in this repo has mutable runtime state. |
+| Operators | Maintainers who change the constant list in source and downstream repos that consume those constants. |
+| Highest-risk actions | Renumbering or repurposing a permission ID that downstream contracts already depend on. |
+| Recovery posture | Runtime admin recovery does not apply here. If the constants are wrong, downstream code and docs have to be updated and redeployed against the corrected source. |
+## Routine Operations
+- Treat `JBPermissionIds.sol` as a coordination artifact across repos, not a place for casual edits.
+- When adding a new permission, update the source library and the dependent repo docs together so operator guidance does not drift from code.
+- Re-check downstream permission assumptions after any change because multiple repos gate admin behavior through this single numbering scheme.
+## One-Way Or High-Risk Actions
+- Changing an existing numeric assignment can silently invalidate permission checks in dependent repos.
+- The library itself has no admin keys, but stale docs around it can mislead operators about real powers elsewhere in the ecosystem.
+## Recovery Notes
+- If the permission map drifts from deployed contracts, the fix is coordinated source and documentation updates in the dependent repos, plus redeployment where the old numeric assumptions are already live.
+- There is no on-chain migration knob in this repo because it only ships compile-time constants.
 ## Overview
 This repo defines permission ID constants. It contains no admin functions itself -- it is a reference library for the permission system used across the Juicebox V6 ecosystem. The constants in `JBPermissionIds` are consumed by contracts in nana-core-v6, nana-721-hook-v6, nana-buyback-hook-v6, nana-router-terminal-v6, and nana-suckers-v6 to gate privileged operations.
@@ -10,7 +35,7 @@ There are no ownable contracts, no upgrade mechanisms, and no mutable state. The
 ## Permission IDs
-All 34 defined permission IDs and what they control:
+All 39 defined permission IDs and what they control:
 | ID | Constant | Used By | What It Controls |
 |----|----------|---------|-----------------|
@@ -48,8 +73,13 @@ All 34 defined permission IDs and what they control:
 | 32 | `DEPLOY_SUCKERS` | nana-suckers (`JBSuckerRegistry`) | `JBSuckerRegistry.deploySuckersFor` -- deploy sucker contracts for cross-chain bridging. |
 | 33 | `SUCKER_SAFETY` | nana-suckers (`JBSucker`) | `JBSucker.enableEmergencyHatchFor` -- enable the emergency hatch to recover stuck tokens. |
 | 34 | `SET_SUCKER_DEPRECATION` | nana-suckers (`JBSucker`) | `JBSucker.setDeprecation` -- set deprecation status (ENABLED, DEPRECATION_PENDING, SENDING_DISABLED, DEPRECATED). |
+| 35 | `HIDE_TOKENS` | revnet-core (`REVHiddenTokens`) | `REVHiddenTokens.hideTokensOf` -- hide (burn) tokens on behalf of a holder. Checked against the **token holder**. |
+| 36 | `OPEN_LOAN` | revnet-core (`REVLoans`) | `REVLoans.borrowFrom` -- open a loan on behalf of a token holder. Checked against the **token holder**. |
+| 37 | `REALLOCATE_LOAN` | revnet-core (`REVLoans`) | `REVLoans.reallocateCollateralFromLoan` -- reallocate loan collateral on behalf of a loan NFT owner. Checked against the **loan NFT owner**. |
+| 38 | `REPAY_LOAN` | revnet-core (`REVLoans`) | `REVLoans.repayLoan` -- repay a loan on behalf of a loan NFT owner. Checked against the **loan NFT owner**. |
+| 39 | `REVEAL_TOKENS` | revnet-core (`REVHiddenTokens`) | `REVHiddenTokens.revealTokensOf` -- reveal (re-mint) hidden tokens on behalf of a holder. Checked against the **token holder**. |
-IDs 0 and 35-255 are unused. ID 0 is reserved and cannot be set. IDs 35-255 are available for future ecosystem extensions.
+IDs 0 and 40-255 are unused. ID 0 is reserved and cannot be set. IDs 40-255 are available for future ecosystem extensions.
 ## ROOT Permission
@@ -99,7 +129,7 @@ Some permissions warrant extra caution when granting:
 ## Holder vs. Owner Permissions
-Most permissions are checked against the **project owner** (the account that owns the project NFT). Four permissions are instead checked against the **token holder**:
+Most permissions are checked against the **project owner** (the account that owns the project NFT). Several permissions are instead checked against the **token holder** or **loan NFT owner**:
 | Permission | Checked Against |
 |-----------|----------------|
@@ -107,5 +137,10 @@ Most permissions are checked against the **project owner** (the account that own
 | `BURN_TOKENS` (11) | Token holder |
 | `CLAIM_TOKENS` (12) | Token holder |
 | `TRANSFER_CREDITS` (13) | Token holder |
+| `HIDE_TOKENS` (35) | Token holder |
+| `OPEN_LOAN` (36) | Token holder |
+| `REALLOCATE_LOAN` (37) | Loan NFT owner |
+| `REPAY_LOAN` (38) | Loan NFT owner |
+| `REVEAL_TOKENS` (39) | Token holder |
-This means a token holder can grant an operator permission to cash out, burn, claim, or transfer their own tokens -- independent of the project owner's permissions.
+This means a token holder can grant an operator permission to cash out, burn, claim, transfer, hide, reveal, or borrow against their own tokens -- independent of the project owner's permissions. Loan NFT owners can similarly grant operators permission to repay or reallocate their loans.

package/ARCHITECTURE.md CHANGED Viewed

@@ -1,67 +1,42 @@
-# nana-permission-ids-v6 — Architecture
+# Architecture
 ## Purpose
-Constants library defining permission IDs used throughout the Juicebox V6 ecosystem. These IDs are used with `JBPermissions` to control access to protocol functions.
-## 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
-```
-src/
-└── JBPermissionIds.sol — Library of uint8 permission ID constants
-```
-## Permission ID Registry
-| ID | Name | Used By | Gated Function |
-|----|------|---------|----------------|
-| 1 | `ROOT` | nana-core | All permissions (dangerous) |
-| 2 | `QUEUE_RULESETS` | nana-core | `JBController.queueRulesetsOf` |
-| 3 | `LAUNCH_RULESETS` | nana-core | `JBController.launchRulesetsFor` |
-| 4 | `CASH_OUT_TOKENS` | nana-core | `JBMultiTerminal.cashOutTokensOf` |
-| 5 | `SEND_PAYOUTS` | nana-core | `JBMultiTerminal.sendPayoutsOf` |
-| 6 | `MIGRATE_TERMINAL` | nana-core | `JBMultiTerminal.migrateBalanceOf` |
-| 7 | `SET_PROJECT_URI` | nana-core | `JBController.setUriOf` |
-| 8 | `DEPLOY_ERC20` | nana-core | `JBController.deployERC20For` |
-| 9 | `SET_TOKEN` | nana-core | `JBController.setTokenFor` |
-| 10 | `MINT_TOKENS` | nana-core | `JBController.mintTokensOf` |
-| 11 | `BURN_TOKENS` | nana-core | `JBController.burnTokensOf` |
-| 12 | `CLAIM_TOKENS` | nana-core | `JBController.claimTokensFor` |
-| 13 | `TRANSFER_CREDITS` | nana-core | `JBController.transferCreditsFrom` |
-| 14 | `SET_CONTROLLER` | nana-core | `JBDirectory.setControllerOf` |
-| 15 | `SET_TERMINALS` | nana-core | `JBDirectory.setTerminalsOf` |
-| 16 | `ADD_TERMINALS` | nana-core | `JBDirectory.setPrimaryTerminalOf` (implicit add) |
-| 17 | `SET_PRIMARY_TERMINAL` | nana-core | `JBDirectory.setPrimaryTerminalOf` |
-| 18 | `USE_ALLOWANCE` | nana-core | `JBMultiTerminal.useAllowanceOf` |
-| 19 | `SET_SPLIT_GROUPS` | nana-core | `JBController.setSplitGroupsOf` |
-| 20 | `ADD_PRICE_FEED` | nana-core | `JBController.addPriceFeedFor` |
-| 21 | `ADD_ACCOUNTING_CONTEXTS` | nana-core | `JBMultiTerminal.addAccountingContextsFor` |
-| 22 | `SET_TOKEN_METADATA` | nana-core | `JBController.setTokenMetadataOf` |
-| 23 | `ADJUST_721_TIERS` | nana-721-hook | `JB721TiersHook.adjustTiers` |
-| 24 | `SET_721_METADATA` | nana-721-hook | `JB721TiersHook.setMetadata` |
-| 25 | `MINT_721` | nana-721-hook | `JB721TiersHook.mintFor` |
-| 26 | `SET_721_DISCOUNT_PERCENT` | nana-721-hook | `JB721TiersHook.setDiscountPercentOf` |
-| 27 | `SET_BUYBACK_TWAP` | nana-buyback-hook | `JBBuybackHook.setTwapWindowOf` |
-| 28 | `SET_BUYBACK_POOL` | nana-buyback-hook | `JBBuybackHook.setPoolFor` |
-| 29 | `SET_BUYBACK_HOOK` | nana-buyback-hook | `JBBuybackHookRegistry.setHookFor` + `lockHookFor` |
-| 30 | `SET_ROUTER_TERMINAL` | nana-router-terminal | `JBRouterTerminalRegistry.setTerminalFor` + `lockTerminalFor` |
-| 31 | `MAP_SUCKER_TOKEN` | nana-suckers | `JBSucker.mapToken` |
-| 32 | `DEPLOY_SUCKERS` | nana-suckers | `JBSuckerRegistry.deploySuckersFor` |
-| 33 | `SUCKER_SAFETY` | nana-suckers | `JBSucker.enableEmergencyHatchFor` |
-| 34 | `SET_SUCKER_DEPRECATION` | nana-suckers | `JBSucker.setDeprecation` |
+`nana-permission-ids-v6` is the shared permission namespace for the ecosystem. It exists so every repo can agree on what permission bit means what.
+## Boundaries
+- This repo intentionally contains almost no logic.
+- Its value is stability, not sophistication.
+- The constants here are coupled to checks spread across many sibling repos.
+## Main Components
+| Component | Responsibility |
+| --- | --- |
+| `JBPermissionIds` | Defines the canonical `uint8` IDs used with `JBPermissions` |
+## Runtime Model
+There is no runtime state. Other repos import this library and compare permission bits against these constants.
+## Critical Invariants
+- Existing IDs must remain stable once consumed by deployed contracts and integrations.
+- New IDs should only be appended intentionally; repurposing an old ID is ecosystem-breaking.
+- `ROOT` stays special and must remain consistent with `JBPermissions` expectations.
+## Where Complexity Lives
+- The code is trivial; the coordination burden is not.
+- Mistakes here look like harmless renames until they land in downstream permission checks.
 ## Dependencies
-None — this is a leaf dependency with no imports.
+- Semantically coupled to `nana-core-v6` and every repo that performs permission checks
+## Safe Change Guide
+- Treat every ID change as a cross-repo protocol change.
+- When adding a permission, update the docs and downstream repos in the same change set.
+- Do not add convenience aliases that obscure the one-to-one mapping between bit position and meaning.

package/AUDIT_INSTRUCTIONS.md CHANGED Viewed

@@ -1,184 +1,34 @@
-# Audit Instructions -- nana-permission-ids-v6
+# Audit Instructions
-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 34 `uint8` constants. Read [RISKS.md](./RISKS.md) first -- it documents all known risks and trust assumptions. Then come back here.
+This repo is only permission ID constants, but the constants are security-critical because many repos key access control off them.
-## Quick Verification
+## Objective
-Run this one-liner from the repo root to verify all 34 permission IDs are unique, sequential (1-34), and have no gaps or duplicates:
-```bash
-grep 'constant.*=' src/JBPermissionIds.sol | sed 's/.*= \([0-9]*\).*/\1/' | sort -n | diff - <(seq 1 34) && echo "PASS: All 34 IDs are unique and sequential (1-34)" || 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.
+Find issues that:
+- assign duplicate IDs to different semantic permissions
+- mismatch IDs that downstream repos assume are canonical
+- create ordering or collision hazards for future permission additions
 ## Scope
-**In scope:**
-```
-src/JBPermissionIds.sol    # Constants library (~69 lines, 34 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 34 `uint8 internal constant` values numbered 1 through 34. 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-34:** Individual permissions, each gating a specific function (or set of functions) in the ecosystem.
-- **Bits 35-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 | `ADD_TERMINALS` | `JBDirectory.setPrimaryTerminalOf` (implicit add) | Project owner |
-| 17 | `SET_PRIMARY_TERMINAL` | `JBDirectory.setPrimaryTerminalOf` | Project owner |
-| 18 | `USE_ALLOWANCE` | `JBMultiTerminal.useAllowanceOf` | Project owner |
-| 19 | `SET_SPLIT_GROUPS` | `JBController.setSplitGroupsOf` | Project owner |
-| 20 | `ADD_PRICE_FEED` | `JBController.addPriceFeedFor` (not `JBPrices` directly) | Project owner |
-| 21 | `ADD_ACCOUNTING_CONTEXTS` | `JBMultiTerminal.addAccountingContextsFor` | Project owner |
-| 22 | `SET_TOKEN_METADATA` | `JBController.setTokenMetadataOf` | Project owner |
-| 23 | `ADJUST_721_TIERS` | `JB721TiersHook.adjustTiers` | Hook owner |
-| 24 | `SET_721_METADATA` | `JB721TiersHook.setMetadata` | Hook owner |
-| 25 | `MINT_721` | `JB721TiersHook.mintFor` | Hook owner |
-| 26 | `SET_721_DISCOUNT_PERCENT` | `JB721TiersHook.setDiscountPercentOf` | Hook owner |
-| 27 | `SET_BUYBACK_TWAP` | `JBBuybackHook.setTwapWindowOf` | Project owner |
-| 28 | `SET_BUYBACK_POOL` | `JBBuybackHook.setPoolFor` | Project owner |
-| 29 | `SET_BUYBACK_HOOK` | `JBBuybackHookRegistry.setHookFor` + `lockHookFor` | Project owner |
-| 30 | `SET_ROUTER_TERMINAL` | `JBRouterTerminalRegistry.setTerminalFor` + `lockTerminalFor` | Project owner |
-| 31 | `MAP_SUCKER_TOKEN` | `JBSucker.mapToken` | Project owner |
-| 32 | `DEPLOY_SUCKERS` | `JBSuckerRegistry.deploySuckersFor` | Project owner |
-| 33 | `SUCKER_SAFETY` | `JBSucker.enableEmergencyHatchFor` | Project owner |
-| 34 | `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 34 constants have distinct values.
-- Values are sequential from 1 to 34 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-22 should match the `_requirePermissionFrom` calls in `JBController`, `JBMultiTerminal`, and `JBDirectory`.
-- **nana-721-hook-v6**: IDs 23-26 should match permission checks in `JB721TiersHook`.
-- **nana-buyback-hook-v6**: IDs 27-29 should match permission checks in `JBBuybackHook` and `JBBuybackHookRegistry`.
-- **nana-router-terminal-v6**: ID 30 should match permission checks in `JBRouterTerminalRegistry`.
-- **nana-suckers-v6**: IDs 31-34 should match permission checks in `JBSucker` and `JBSuckerRegistry`.
-### 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 (29)**: Gates both `setHookFor` (configurable) and `lockHookFor` (permanent). An operator with this permission can permanently lock the hook configuration.
-- **SET_ROUTER_TERMINAL (30)**: 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).
+In scope:
+- `src/JBPermissionIds.sol`
-## Invariants to Verify
+## Critical Invariants
-1. **Uniqueness**: All 34 constants have unique values in the range [1, 34].
-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 34 with no gaps.
+1. Each permission semantic has one stable numeric ID.
+2. No two distinct permissions share an ID.
+3. IDs match the expectations of all dependent repos in this workspace.
+4. IDs 35-39 (revnet-core delegation: `HIDE_TOKENS`, `OPEN_LOAN`, `REALLOCATE_LOAN`, `REPAY_LOAN`, `REVEAL_TOKENS`) are consumed by `revnet-core-v6` — verify they match the values used in `REVHiddenTokens` and `REVLoans`.
-## Testing Setup
+## Threat Model
-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.
+Prioritize stale or inconsistent constants, especially where wildcard grants or deployer permissions depend on a specific numeric value.
-```bash
-cd nana-permission-ids-v6
-forge build  # Ensures the library compiles
-```
+## Build And Verification
-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/
-```
+Standard workflow:
+- `npm install`
+- `forge build`
-Go break it.
+A meaningful finding here should show a real downstream permission check becoming broader, narrower, or mismatched because of the constant set.

package/CHANGELOG.md ADDED Viewed

@@ -0,0 +1,49 @@
+# Changelog
+## Scope
+This file describes the verified change from `nana-permission-ids-v5` to the current `nana-permission-ids-v6` repo.
+## Current v6 surface
+- `JBPermissionIds`
+## Summary
+- The numeric permission map shifted. `LAUNCH_RULESETS` was inserted near the top of the sequence and every downstream numeric value moved with it.
+- v6 adds permissions for capabilities that did not exist in the old map, including `LAUNCH_RULESETS`, `ADD_TERMINALS`, `SET_TOKEN_METADATA`, `SET_BUYBACK_HOOK`, `SET_ROUTER_TERMINAL`, and `SET_SUCKER_DEPRECATION`.
+- The old swap-terminal-specific permissions are gone because the deployed ecosystem no longer centers on `nana-swap-terminal-v5`.
+- `SUCKER_SAFETY` no longer covers every safety action by itself. `SET_SUCKER_DEPRECATION` is its own permission in v6.
+## v6 additions: revnet-core delegation (IDs 35–39)
+- `HIDE_TOKENS` (35) — hide tokens on behalf of a holder via `REVHiddenTokens.hideTokensOf`. Checked against the token holder.
+- `OPEN_LOAN` (36) — open a loan on behalf of a token holder via `REVLoans.borrowFrom`. Checked against the token holder.
+- `REALLOCATE_LOAN` (37) — reallocate loan collateral on behalf of a loan NFT owner via `REVLoans.reallocateCollateralFromLoan`. Checked against the loan NFT owner.
+- `REPAY_LOAN` (38) — repay a loan on behalf of a loan NFT owner via `REVLoans.repayLoan`. Checked against the loan NFT owner.
+- `REVEAL_TOKENS` (39) — reveal hidden tokens on behalf of a holder via `REVHiddenTokens.revealTokensOf`. Checked against the token holder.
+These are consumed by `revnet-core-v6` and checked via `JBPermissioned._requirePermissionFrom` (for `REVHiddenTokens`) or inline `PERMISSIONS.hasPermission` calls (for `REVLoans`).
+## Verified deltas
+- `QUEUE_RULESETS` no longer also covers `launchRulesetsFor`; `LAUNCH_RULESETS` is its own constant.
+- `ADD_TERMINALS` was inserted between `SET_TERMINALS` and `SET_PRIMARY_TERMINAL`.
+- `SET_TOKEN_METADATA`, `SET_BUYBACK_HOOK`, `SET_ROUTER_TERMINAL`, and `SET_SUCKER_DEPRECATION` are new constants.
+- `ADD_SWAP_TERMINAL_POOL` and `ADD_SWAP_TERMINAL_TWAP_PARAMS` were removed.
+## Breaking ABI changes
+- There is no runtime contract ABI to port here.
+- The breaking surface is compile-time and application-logic-level: constant names, meanings, and numeric values changed.
+## Indexer impact
+- None directly from this repo.
+- Indirectly, any off-chain access-control model keyed to raw numeric IDs must be updated.
+## Migration notes
+- Hardcoded numeric permission IDs from v5 are stale and unsafe.
+- Rebuild every permission check from the named v6 constants.
+- Treat this repo as application-logic-critical even though it is not a large runtime surface.

package/README.md CHANGED Viewed

@@ -1,119 +1,59 @@
 # Juicebox Permission IDs
-The single source of truth for access control across the Juicebox V6 ecosystem. This library defines 34 `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.
+`@bananapus/permission-ids-v6` is the shared constant library for Juicebox V6 operator permissions. It gives every repo in the ecosystem the same numeric meaning for the same permission name.
-## How permissions work
+Architecture: [ARCHITECTURE.md](./ARCHITECTURE.md)
-Juicebox V6 access control is built on a simple model: an **account** (typically a project owner) grants an **operator** (any address) a set of permission IDs scoped to a specific **project ID**. When a permissioned function is called, the contract checks that the caller either *is* the account or *has* the required permission ID for that project.
+## Overview
-Permissions are stored as a 256-bit packed integer in `JBPermissions`, where each bit position corresponds to a permission ID. This library provides human-readable names for those bit positions.
+The library is intentionally simple: one Solidity file, no storage, no deployment, and no runtime logic. Its value comes from consistency.
-```
-permissionsOf[operator][account][projectId] => uint256 (packed bits)
-```
+`JBPermissions` stores operator permissions as packed bits. This package names the bit positions so integrations do not drift across repos.
-## Architecture
+Use this repo as the single source of truth for permission numbers. Do not redefine permission IDs locally in downstream repos.
-| Contract | Description |
-|----------|-------------|
-| `JBPermissionIds` | Solidity library with 34 `uint8 internal constant` permission IDs (values 1--34). No state, no functions, no dependencies. Pragma `^0.8.0` for maximum compatibility. |
+If the question is "who can do this action?" you will still need `JBPermissions` in `nana-core-v6`. This repo only tells you what the numeric labels mean.
-## Repository Layout
+## Current Permission Ranges
-```
-src/
-└── JBPermissionIds.sol  ── 34 uint8 constants (the only source file)
-```
+| Range | Area |
+| --- | --- |
+| `1` | global `ROOT` permission |
+| `2-22` | core protocol permissions |
+| `23-26` | 721 hook permissions |
+| `27-29` | buyback hook permissions |
+| `30` | router terminal permission |
+| `31-34` | sucker and omnichain permissions |
+| `35-39` | revnet-core permissions (hidden tokens, loans) |
+The exact constants live in `src/JBPermissionIds.sol`.
-No tests, interfaces, or deployment scripts -- this repo is a pure constant library.
-## All permission IDs
-### Global (ID 1)
-| ID | Name | Description |
-|----|------|-------------|
-| 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--22) -- [nana-core-v6](https://github.com/Bananapus/nana-core-v6)
-| ID | Name | Checked in | Description |
-|----|------|------------|-------------|
-| 2 | `QUEUE_RULESETS` | `JBController.queueRulesetsOf` | Queue new rulesets for a project. Also required by `JB721TiersHookProjectDeployer` and `JBOmnichainDeployer`. |
-| 3 | `LAUNCH_RULESETS` | `JBController.launchRulesetsFor` | Launch a project's initial rulesets and terminals. Note: the caller also needs `SET_TERMINALS` (ID 15) since this function configures terminals. |
-| 4 | `CASH_OUT_TOKENS` | `JBMultiTerminal.cashOutTokensOf` | Cash out (redeem) a holder's tokens for a share of the project's surplus. Checked against the **token holder**, not the project owner. |
-| 5 | `SEND_PAYOUTS` | `JBMultiTerminal.sendPayoutsOf` | Send payouts to a project's splits up to its payout limit. |
-| 6 | `MIGRATE_TERMINAL` | `JBMultiTerminal.migrateBalanceOf` | Migrate a project's balance from one terminal to another. |
-| 7 | `SET_PROJECT_URI` | `JBController.setUriOf` | Set a project's metadata URI. |
-| 8 | `DEPLOY_ERC20` | `JBController.deployERC20For` | Deploy a new ERC-20 token for a project. |
-| 9 | `SET_TOKEN` | `JBController.setTokenFor` | Set an existing ERC-20 token for a project. |
-| 10 | `MINT_TOKENS` | `JBController.mintTokensOf` | Mint new project tokens. Only works if the current ruleset allows owner minting. |
-| 11 | `BURN_TOKENS` | `JBController.burnTokensOf` | Burn a holder's project tokens. Checked against the **token holder**, not the project owner. |
-| 12 | `CLAIM_TOKENS` | `JBController.claimTokensFor` | Claim a holder's internal credit balance as ERC-20 tokens. Checked against the **token holder**. |
-| 13 | `TRANSFER_CREDITS` | `JBController.transferCreditsFrom` | Transfer a holder's internal credit balance to another address. Checked against the **token holder**. |
-| 14 | `SET_CONTROLLER` | `JBDirectory.setControllerOf` | Set a project's controller in the directory. |
-| 15 | `SET_TERMINALS` | `JBDirectory.setTerminalsOf` | Set a project's terminals. **Warning:** can remove the primary terminal. Also required by `LAUNCH_RULESETS` (ID 3). |
-| 16 | `ADD_TERMINALS` | `JBDirectory.setPrimaryTerminalOf` | Add a new terminal to a project when `setPrimaryTerminalOf` implicitly adds it. |
-| 17 | `SET_PRIMARY_TERMINAL` | `JBDirectory.setPrimaryTerminalOf` | Set a project's primary terminal for a given token. |
-| 18 | `USE_ALLOWANCE` | `JBMultiTerminal.useAllowanceOf` | Use a project's surplus allowance to send funds to an arbitrary address. |
-| 19 | `SET_SPLIT_GROUPS` | `JBController.setSplitGroupsOf` | Set a project's split groups (how payouts and reserved tokens are distributed). |
-| 20 | `ADD_PRICE_FEED` | `JBController.addPriceFeedFor` | Add a price feed for a project. The controller checks this permission before calling `JBPrices.addPriceFeedFor`. |
-| 21 | `ADD_ACCOUNTING_CONTEXTS` | `JBMultiTerminal.addAccountingContextsFor` | Add accounting contexts (accepted tokens) to a terminal for a project. |
-| 22 | `SET_TOKEN_METADATA` | `JBController.setTokenMetadataOf` | Set a project token's name and symbol. Checked against the project owner. |
-### 721 Hook (IDs 23--26) -- [nana-721-hook-v6](https://github.com/Bananapus/nana-721-hook-v6)
-| ID | Name | Checked in | Description |
-|----|------|------------|-------------|
-| 23 | `ADJUST_721_TIERS` | `JB721TiersHook.adjustTiers` | Add or remove NFT tiers. Also used by `CTPublisher` and `CTProjectOwner` in croptop-core-v6. |
-| 24 | `SET_721_METADATA` | `JB721TiersHook.setMetadata` | Set the metadata (base URI, contract URI, token URI resolver) for a 721 hook. |
-| 25 | `MINT_721` | `JB721TiersHook.mintFor` | Manually mint NFTs from specific tiers to a beneficiary. |
-| 26 | `SET_721_DISCOUNT_PERCENT` | `JB721TiersHook.setDiscountPercentOf` | Set the discount percent for one or more NFT tiers. |
-### Buyback Hook (IDs 27--29) -- [nana-buyback-hook-v6](https://github.com/Bananapus/nana-buyback-hook-v6)
-| ID | Name | Checked in | Description |
-|----|------|------------|-------------|
-| 27 | `SET_BUYBACK_TWAP` | `JBBuybackHook.setTwapWindowOf` | Set the TWAP (time-weighted average price) oracle window for a project's buyback hook. |
-| 28 | `SET_BUYBACK_POOL` | `JBBuybackHook.setPoolFor`, `JBBuybackHook.initializePoolFor`, `JBBuybackHookRegistry.setPoolFor`, `JBBuybackHookRegistry.initializePoolFor` | Set the Uniswap pool for a project's buyback hook. |
-| 29 | `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 30) -- [nana-router-terminal-v6](https://github.com/Bananapus/nana-router-terminal-v6)
-| ID | Name | Checked in | Description |
-|----|------|------------|-------------|
-| 30 | `SET_ROUTER_TERMINAL` | `JBRouterTerminalRegistry.setTerminalFor`, `JBRouterTerminalRegistry.lockTerminalFor` | Set or lock the router terminal for a project. |
-### Suckers / Omnichain (IDs 31--34) -- [nana-suckers-v6](https://github.com/Bananapus/nana-suckers-v6)
-| ID | Name | Checked in | Description |
-|----|------|------------|-------------|
-| 31 | `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. |
-| 32 | `DEPLOY_SUCKERS` | `JBSuckerRegistry.deploySuckersFor` | Deploy new sucker contracts for a project. Also checked by `JBOmnichainDeployer` and `CTDeployer`. |
-| 33 | `SUCKER_SAFETY` | `JBSucker.enableEmergencyHatchFor` | Enable the emergency hatch for a sucker, allowing the project owner to recover stuck tokens. |
-| 34 | `SET_SUCKER_DEPRECATION` | `JBSucker.setDeprecation` | Set the deprecation status of a sucker (ENABLED, DEPRECATION_PENDING, SENDING_DISABLED, DEPRECATED). |
-## Gotchas
-- **ROOT is dangerous.** It grants every permission on every contract. An operator with ROOT for project 5 can queue rulesets, send payouts, migrate terminals, mint tokens, etc. -- all on behalf of the granting account for that project.
-- **ROOT cannot be granted for the wildcard project ID.** `JBPermissions` reverts with `JBPermissions_CantSetRootPermissionForWildcardProject()` if you try to set ROOT with `projectId = 0`. This prevents a single operator from controlling all of an account's projects.
-- **ROOT operators can set permissions for others, but cannot grant ROOT.** A ROOT operator can call `setPermissionsFor` on behalf of the account, but only if the new permission set does NOT include ROOT and is NOT for the wildcard project ID.
-- **Permission ID 0 is reserved.** `JBPermissions` reverts with `JBPermissions_NoZeroPermission()` if bit 0 is set in any packed permission value. IDs start at 1.
-- **Wildcard project ID (0) applies to all projects.** Granting a permission with `projectId = 0` means the operator has that permission for every project owned by the account. Use with caution.
-- **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.
-- **ADD_TERMINALS (16) vs SET_TERMINALS (15).** `SET_TERMINALS` replaces the entire terminal list and can remove the primary terminal. `ADD_TERMINALS` is a narrower permission checked when `setPrimaryTerminalOf` implicitly adds a new terminal that is not already in the project's terminal list.
-- **The uint8 type limits IDs to 0--255.** Currently 34 are defined (1--34), leaving room for future extensions.
+## Mental Model
+This repo is a coordination artifact, not a behavior repo. Its value is that every other package can import the same names and mean the same thing.
 ## Install
+```bash
+npm install @bananapus/permission-ids-v6
+```
+## Development
 ```bash
 npm install
+forge build
+```
+## Repository Layout
+```text
+src/
+  JBPermissionIds.sol
 ```
-## Develop
+## Risks And Notes
-| Command | Description |
-|---------|-------------|
-| `forge build` | Compile contracts |
+- `ROOT` is intentionally powerful and should be granted sparingly
+- wildcard project scope is convenient but easy to misuse operationally
+- any change to this file has ecosystem-wide consequences because other repos assume the values are stable