@bananapus/core-v6 0.0.30 → 0.0.31

package/USER_JOURNEYS.md

@@ -1,668 +1,117 @@
-# nana-core-v6 -- User Journeys
+# User Journeys
 
-All user paths through the Juicebox V6 core protocol. For each journey: entry point, key parameters, state changes, events, and edge cases.
+## Who This Repo Serves
 
----
+- founders launching and evolving Juicebox projects
+- supporters paying projects in the asset a terminal accepts
+- token holders cashing out against project surplus
+- operators managing permissions, splits, fund access limits, and rulesets
+- integrators wiring hooks, terminals, price feeds, and migrations into the canonical protocol surface
 
-## 1. Launch Project
+## Journey 1: Launch A Project With The Right Initial Shape
 
-**Entry point**: `JBController.launchProjectFor(address owner, string projectUri, JBRulesetConfig[] rulesetConfigurations, JBTerminalConfig[] terminalConfigurations, string memo)`
+**Starting state:** you know who should own the project, which terminals it should use, and what the first ruleset should allow.
 
-**Who can call**: Anyone. The project ERC-721 is minted to the specified `owner`.
+**Success:** the project NFT exists, the initial ruleset is active, accepted terminals are installed, and downstream hooks or splits can begin working immediately.
 
-**Parameters**:
-- `owner` -- Address that receives the project ERC-721 NFT
-- `projectUri` -- Metadata URI (typically IPFS hash)
-- `rulesetConfigurations` -- Array of `JBRulesetConfig` structs defining the project's economic rules
-- `terminalConfigurations` -- Array of `JBTerminalConfig` structs specifying which terminals accept which tokens
-- `memo` -- Arbitrary string emitted in the event
+**Flow**
+1. Call `JBController.launchProjectFor(...)` with the owner, URI, ruleset config, terminal configs, and any split or hook metadata.
+2. `JBProjects` mints the project NFT, `JBDirectory` records controller and terminal routing, and `JBRulesets` stores the first ruleset.
+3. If the project wants ERC-20 tokens, reserved-rate behavior, or hook-driven behavior, that configuration is committed at launch instead of being inferred later.
+4. The project can now accept payments and queue future rulesets without changing project identity.
 
-**State changes**:
-1. `JBProjects.createFor(owner)` -- Mints ERC-721, increments project count, returns `projectId`
-2. `uriOf[projectId] = projectUri` -- Stores metadata URI (if non-empty)
-3. `JBDirectory.setControllerOf(projectId, controller)` -- Sets this controller as the project's controller
-4. For each terminal config: `terminal.addAccountingContextsFor(projectId, contexts)` -- Registers accepted tokens
-5. `JBDirectory.setTerminalsOf(projectId, terminals)` -- Registers terminals
-6. For each ruleset config:
-   - `JBRulesets.queueFor(...)` -- Creates ruleset with packed intrinsic/user properties and metadata
-   - `JBSplits.setSplitGroupsOf(...)` -- Stores split groups for the ruleset
-   - `JBFundAccessLimits.setFundAccessLimitsFor(...)` -- Stores payout limits and surplus allowances
+**Failure cases that matter:** mismatched accounting contexts, wrong terminals for the target asset, invalid hook metadata, and launching with permissions or ownership assumptions that cannot be repaired cleanly later.
 
-**Events**: `LaunchProject(rulesetId, projectId, projectUri, memo, caller)`
+## Journey 2: Accept A Payment And Issue The Right Token Exposure
 
-**Edge cases**:
-- Empty `rulesetConfigurations` array is valid -- project launches with no rulesets (cannot receive payments until rulesets are launched via `launchRulesetsFor`)
-- Multiple rulesets can be queued in a single launch -- they form a linked list
-- If `block.timestamp` collision occurs for rulesetId, the ID is incremented by 1
+**Starting state:** the project has an active ruleset and a terminal that accepts the payer's asset.
 
----
+**Success:** treasury balances increase, hooks run in the right order, and the beneficiary receives credits or ERC-20 tokens consistent with the ruleset.
 
-## 2. Pay a Project
+**Flow**
+1. A payer calls `pay(...)` on `JBMultiTerminal`.
+2. The terminal validates the accounting context, records funds, and asks `JBTerminalStore` to derive issuance from the active ruleset.
+3. `JBController` and `JBTokens` decide whether the beneficiary gets project token credits, ERC-20s, or no issuance because weight is zero.
+4. Any configured pay hooks or data hooks run around the accounting path.
 
-**Entry point**: `JBMultiTerminal.pay(uint256 projectId, address token, uint256 amount, address beneficiary, uint256 minReturnedTokens, string memo, bytes metadata)`
+**Edge conditions that change user experience:** paused payments, custom hook side effects, fee-on-transfer tokens, unsupported price feeds, zero-weight rulesets, and permit-based flows.
 
-**Who can call**: Anyone.
+## Journey 3: Turn Credits Into ERC-20 Tokens Once A Project Wants A Transferable Token
 
-**Parameters**:
-- `projectId` -- The project to pay
-- `token` -- Token address (`JBConstants.NATIVE_TOKEN` for ETH)
-- `amount` -- Amount of tokens (ignored for native token; uses `msg.value`)
-- `beneficiary` -- Address to receive minted project tokens
-- `minReturnedTokens` -- Slippage protection; reverts if fewer tokens minted
-- `memo` -- Arbitrary string
-- `metadata` -- Bytes; may contain Permit2 data (keyed by `"permit2"` ID) and/or hook-specific data
+**Starting state:** users already have project token credits and the project now wants an ERC-20 representation.
 
-**State changes**:
-1. Tokens transferred to terminal (or `msg.value` accepted)
-2. `JBTerminalStore.balanceOf[terminal][projectId][token]` incremented (minus any hook-diverted amounts)
-3. `JBTokens` mints project tokens to beneficiary (credits or ERC-20)
-4. `JBController.pendingReservedTokenBalanceOf[projectId]` incremented by reserved portion
-5. Pay hooks execute (if data hook returns specifications)
+**Success:** the project deploys or installs its ERC-20 token and holders can claim credits into transferable balances.
 
-**Events**: `Pay(rulesetId, rulesetCycleNumber, projectId, payer, beneficiary, amount, newlyIssuedTokenCount, memo, metadata, caller)`
+**Flow**
+1. Deploy or set the project's ERC-20 token through `JBController`.
+2. Holders or operators call `claimTokensFor(...)` to convert credits into ERC-20 balances for a beneficiary.
+3. Future issuance can continue using the same project identity while users now interact with a standard token surface.
 
-**Edge cases**:
-- `amount = 0` is valid -- records a zero payment, mints 0 tokens
-- `beneficiary = address(0)` -- tokens minted to zero address (effectively burned on mint)
-- If `pausePay` is set in ruleset metadata, `recordPaymentFrom` reverts
-- Token count = `mulDiv(amount.value, weight, weightRatio)` -- if weight is 0, no tokens minted
-- Data hook can return empty weight (0) to suppress minting while still recording payment
-- Fee-on-transfer tokens: actual amount received is `_balanceOf(token) - balanceBefore` (measured via balance diff)
+## Journey 4: Distribute Treasury Funds Through Governed Paths
 
-**Preview**: Call `JBMultiTerminal.previewPayFor(projectId, token, amount, beneficiary, metadata)` to simulate the full payment on-chain -- including data hook effects and the reserved/beneficiary token split. Returns `(ruleset, beneficiaryTokenCount, reservedTokenCount, hookSpecifications)`. This is a `view` function that does not modify state. For lower-level access without the mint split, the terminal delegates to `JBTerminalStore.previewPayFrom(terminal, payer, amount, projectId, beneficiary, metadata)` which returns the raw `(ruleset, tokenCount, hookSpecifications)`.
+**Starting state:** the project has terminal balances and the owner wants payouts or allowance-based withdrawals.
 
----
+**Success:** treasury value leaves only through configured limits, recipients, and fee logic instead of arbitrary admin withdrawals.
 
-## 3. Cash Out Tokens
+**Flow**
+1. Authorized actors call payout or allowance surfaces on the terminal.
+2. `JBFundAccessLimits` bounds how much may leave for the current ruleset cycle.
+3. `JBSplits` fans value out to beneficiaries, projects, hooks, or fee recipients as configured.
+4. `JBTerminalStore` updates balances and fee accounting so later previews and cash outs remain consistent.
 
-**Entry point**: `JBMultiTerminal.cashOutTokensOf(address holder, uint256 projectId, uint256 cashOutCount, address tokenToReclaim, uint256 minTokensReclaimed, address payable beneficiary, bytes metadata)`
+**Failure cases that matter:** stale split expectations, exceeding access limits, downstream hook failures, and assuming allowance withdrawals behave like payouts when fee treatment differs.
 
-**Who can call**: The token holder, or an address with the holder's `CASH_OUT_TOKENS` permission.
+## Journey 5: Let Holders Cash Out Against Surplus
 
-**Parameters**:
-- `holder` -- Address whose tokens are being cashed out
-- `projectId` -- The project to cash out from
-- `cashOutCount` -- Number of project tokens to burn (18 decimals)
-- `tokenToReclaim` -- Terminal token to receive back
-- `minTokensReclaimed` -- Slippage protection
-- `beneficiary` -- Address to receive reclaimed tokens
-- `metadata` -- Hook-specific data
+**Starting state:** a holder owns project token exposure and the project has reclaimable surplus in some terminal.
 
-**State changes**:
-1. `STORE.recordCashOutFor()` -- computes the reclaim amount via bonding curve (using current `totalSupply` which still includes the tokens being cashed out), then decrements `JBTerminalStore.balanceOf[terminal][projectId][token]` by `reclaimAmount + hookSpec amounts`
-2. Project tokens burned via `JBController.burnTokensOf()` (credits first, then ERC-20) -- happens AFTER the reclaim calculation, so the bonding curve sees the pre-burn supply
-3. Reclaimed tokens transferred to beneficiary
-4. Cash out hooks execute (if data hook returns specifications)
-5. Fee taken (2.5%) on total amount eligible for fees, unless beneficiary is feeless. When `cashOutTaxRate == 0`, the fee applies only up to the project's unconsumed fee-free surplus (`_feeFreeSurplusOf`) from intra-terminal payouts -- once depleted, cashouts are fee-free.
+**Success:** the holder burns the intended amount of token exposure and receives the correct reclaim amount under the current ruleset.
 
-**Events**: `CashOutTokens(rulesetId, rulesetCycleNumber, projectId, holder, beneficiary, cashOutCount, cashOutTaxRate, reclaimAmount, metadata, caller)`
+**Flow**
+1. The holder calls `cashOutTokensOf(...)` on the relevant terminal.
+2. `JBTerminalStore` calculates reclaim value using surplus, outstanding token supply, cash-out tax rate, and any pending reserved token effects.
+3. Cash-out hooks can modify behavior or side effects, but the core accounting remains anchored in the terminal store.
+4. Tokens burn and value exits the treasury through the terminal that actually held the asset.
 
-**Preview**: Call `JBMultiTerminal.previewCashOutFrom(holder, projectId, cashOutCount, tokenToReclaim, beneficiary, metadata)` to simulate the full cash out on-chain -- including data hook effects on tax rate, supply, and hook specifications. Returns `(ruleset, reclaimAmount, cashOutTaxRate, hookSpecifications)`. This is a `view` function that does not modify state. The terminal delegates to `JBTerminalStore.previewCashOutFrom(terminal, holder, projectId, cashOutCount, tokenToReclaim, beneficiaryIsFeeless, metadata)` for the bonding curve computation. For a simpler estimate without data hook effects, use `currentTotalReclaimableSurplusOf(projectId, cashOutCount, decimals, currency)` or the 6-param `currentReclaimableSurplusOf` overload.
+**Edge conditions that matter:** fee-free addresses, custom cash-out hooks, preview-versus-execution drift under volatile routing, and multi-terminal surplus that users may misread as single-pool liquidity.
 
-**Edge cases**:
-- `cashOutCount = 0` with `totalSupply = 0` -- returns entire surplus (C-5 known bug)
-- `cashOutTaxRate = MAX (10,000)` -- returns 0 (all surplus locked)
-- `cashOutTaxRate = 0` -- proportional (1:1 against supply) with no discount
-- `cashOutCount >= totalSupply` -- returns entire surplus regardless of tax rate
-- Data hook can override `cashOutTaxRate`, `cashOutCount`, `totalSupply` to arbitrary values
-- Fee is NOT taken when `cashOutTaxRate == 0` UNLESS the project has unconsumed fee-free surplus from intra-terminal payouts (`_feeFreeSurplusOf`). The fee applies only up to the surplus amount and depletes it — preventing round-trip fee bypass while scoping fees precisely to the fee-free inflow.
-- Pending reserved tokens inflate `totalSupply`, reducing individual cash out value (H-4)
+## Journey 6: Queue New Rulesets Without Migrating The Project
 
----
+**Starting state:** the project is live and future economics need to change.
 
-## 4. Send Payouts to Splits
+**Success:** the next ruleset activates on schedule while the project keeps the same identity, treasury, and downstream integrations.
 
-**Entry point**: `JBMultiTerminal.sendPayoutsOf(uint256 projectId, address token, uint256 amount, uint256 currency, uint256 minTokensPaidOut)`
+**Flow**
+1. The owner or an operator with the right permission queues one or more new rulesets through `JBController`.
+2. `JBRulesets` stores the proposed future configuration and any approval hook requirements.
+3. When the active duration elapses, the next approved ruleset becomes live and future pays, payouts, and cash outs follow the new terms.
+4. Existing balances and token history remain intact because only future behavior changed.
 
-**Who can call**: Anyone (unless `ownerMustSendPayouts` is set, then requires `SEND_PAYOUTS` permission from owner).
+**Failure cases that matter:** forgetting approval hooks, queueing incompatible metadata for installed hooks, and assuming a ruleset change can retroactively repair prior accounting.
 
-**Parameters**:
-- `projectId` -- The project distributing payouts
-- `token` -- Token being distributed
-- `amount` -- Amount to distribute (in terms of `currency`)
-- `currency` -- Currency denomination of the amount; must match a configured payout limit's currency
-- `minTokensPaidOut` -- Slippage protection on the actual token amount paid out
+## Journey 7: Migrate A Project To New Terminal Or Controller Surfaces Deliberately
 
-**State changes**:
-1. `JBTerminalStore.balanceOf` decremented by `amountPaidOut` (currency-converted)
-2. `JBTerminalStore.usedPayoutLimitOf` incremented
-3. For each split: funds transferred (split hooks, project terminals, or addresses)
-4. Failed splits: amount returned to project balance via `recordAddedBalanceFor`
-5. Leftover (if splits < 100%): sent to project owner
-6. Fee taken on all non-feeless payouts
+**Starting state:** the project needs to move to a new terminal or controller path without pretending historical balances and routing do not exist.
 
-**Events**: `SendPayouts(rulesetId, rulesetCycleNumber, projectId, projectOwner, amount, amountPaidOut, fee, netLeftoverPayoutAmount, caller)`, `SendPayoutToSplit(...)` per split
+**Success:** migration uses the protocol's explicit surfaces so balances, permissions, and future routing stay coherent.
 
-**Edge cases**:
-- `amount > payout limit` -- reverts with `InadequateControllerPayoutLimit`. Does NOT auto-cap.
-- Empty `fundAccessLimitGroups` for the terminal/token = zero payout limit = always reverts
-- Currency conversion uses `JBPrices` if `currency != accountingContext.currency`
-- Payout limit resets each ruleset cycle (`cycleNumber`)
-- `ownerMustSendPayouts` flag gates who can trigger payouts
-- Individual split failures are caught by try-catch; the payout continues to remaining splits
-- Split percentage uses `mulDiv(amount, split.percent, leftoverPercentage)` -- each split gets its proportion of the remaining amount, not of the original total
+**Flow**
+1. Confirm the active ruleset permits migration and the destination surface is the intended successor.
+2. Use `JBController.migrate(...)` and the terminal-store migration paths instead of manually repointing addresses.
+3. Recheck directory routing and accepted accounting contexts after migration completes.
 
----
+## Journey 8: Hand Off Authority Without Handing Out Root Access
 
-## 5. Use Surplus Allowance
+**Starting state:** the project owner wants operators, delegates, or automation to manage only specific surfaces.
 
-**Entry point**: `JBMultiTerminal.useAllowanceOf(uint256 projectId, address token, uint256 amount, uint256 currency, uint256 minTokensPaidOut, address payable beneficiary, address payable feeBeneficiary, string memo)`
+**Success:** permissions are narrow, auditable, and scoped to the actions the operator actually needs.
 
-**Who can call**: Project owner or address with `USE_ALLOWANCE` permission.
+**Flow**
+1. The owner configures operator permissions in `JBPermissions`.
+2. Downstream calls check those packed permission bits instead of assuming project ownership.
+3. Integrations such as ownable wrappers, hook deployers, and router registries can now respect project-scoped delegation without custom ACL logic.
 
-**Parameters**:
-- `projectId`, `token`, `amount`, `currency` -- What to withdraw and in what denomination
-- `minTokensPaidOut` -- Slippage protection on net amount after fees
-- `beneficiary` -- Receives the withdrawn surplus
-- `feeBeneficiary` -- Receives project #1 tokens minted from the fee payment
-- `memo` -- Arbitrary string
+## Hand-Offs
 
-**State changes**:
-1. `JBTerminalStore.balanceOf` decremented by `usedAmount`
-2. `JBTerminalStore.usedSurplusAllowanceOf` incremented
-3. Fee taken (unless owner or beneficiary is feeless)
-4. Net amount transferred to beneficiary
-
-**Events**: `UseAllowance(rulesetId, rulesetCycleNumber, projectId, beneficiary, feeBeneficiary, amount, amountPaidOut, netAmountPaidOut, memo, caller)`
-
-**Edge cases**:
-- `usedAmount > surplus` -- reverts (`InadequateTerminalStoreBalance`)
-- Surplus allowance resets each ruleset (keyed by `rulesetId`, not `cycleNumber`)
-- Amount validated against surplus BEFORE checking allowance limit
-- If either the owner or the beneficiary is feeless, no fee is taken
-
----
-
-## 6. Mint Tokens (Owner)
-
-**Entry point**: `JBController.mintTokensOf(uint256 projectId, uint256 tokenCount, address beneficiary, string memo, bool useReservedPercent)`
-
-**Who can call**: Project owner, address with `MINT_TOKENS` permission, a project terminal, the data hook, or an address with `hasMintPermissionFor` from the data hook.
-
-**Parameters**:
-- `projectId` -- Target project
-- `tokenCount` -- Total tokens to mint (including reserved portion)
-- `beneficiary` -- Receives the non-reserved tokens
-- `memo` -- Arbitrary string
-- `useReservedPercent` -- If true, applies the ruleset's `reservedPercent`; if false, all tokens go to beneficiary
-
-**State changes**:
-1. `JBTokens.mintFor(beneficiary, beneficiaryTokenCount)` -- Mints non-reserved portion
-2. `pendingReservedTokenBalanceOf[projectId]` incremented by reserved portion
-
-**Events**: `MintTokens(beneficiary, projectId, tokenCount, beneficiaryTokenCount, memo, reservedPercent, caller)`
-
-**Preview**: Call `JBController.previewMintOf(projectId, tokenCount, useReservedPercent)` to see how a mint would split between the beneficiary and reserved token pools under the current ruleset. Returns `(beneficiaryTokenCount, reservedTokenCount)`. This is a `view` function that does not modify state.
-
-**Edge cases**:
-- `tokenCount = 0` -- reverts (`ZeroTokensToMint`)
-- If `allowOwnerMinting` is false in ruleset, only terminals and data hooks can mint
-- If `reservedPercent = 10,000` (100%), all tokens go to pending reserved balance, `beneficiaryTokenCount = 0`
-- Terminal calls this with `useReservedPercent = true` during payments
-
----
-
-## 7. Burn Tokens
-
-**Entry point**: `JBController.burnTokensOf(address holder, uint256 projectId, uint256 tokenCount, string memo)`
-
-**Who can call**: The token holder, an address with the holder's `BURN_TOKENS` permission, or a project terminal.
-
-**Parameters**:
-- `holder` -- Address whose tokens to burn
-- `projectId` -- Project whose tokens are being burned
-- `tokenCount` -- Number of tokens to burn
-- `memo` -- Arbitrary string
-
-**State changes**:
-1. Credits burned first (up to credit balance)
-2. Remaining amount burned from ERC-20 balance (if any)
-3. `JBTokens` reduces credit and/or ERC-20 supply
-
-**Events**: `BurnTokens(holder, projectId, tokenCount, memo, caller)`
-
-**Edge cases**:
-- `tokenCount = 0` -- reverts (`ZeroTokensToBurn`)
-- Credits are always burned first. If holder has 100 credits and 50 ERC-20, burning 120 burns all 100 credits + 20 ERC-20.
-- Terminal calls this during cash outs
-
----
-
-## 8. Queue New Ruleset
-
-**Entry point**: `JBController.queueRulesetsOf(uint256 projectId, JBRulesetConfig[] rulesetConfigurations, string memo)`
-
-**Who can call**: Project owner, address with `QUEUE_RULESETS` permission, or the `OMNICHAIN_RULESET_OPERATOR`.
-
-**Parameters**:
-- `projectId` -- Target project
-- `rulesetConfigurations` -- Array of ruleset configs to queue
-- `memo` -- Arbitrary string
-
-**State changes**:
-1. For each config:
-   - `JBRulesets.queueFor(...)` -- Creates new ruleset in linked list
-   - `JBSplits.setSplitGroupsOf(...)` -- Sets splits for the new ruleset
-   - `JBFundAccessLimits.setFundAccessLimitsFor(...)` -- Sets limits for the new ruleset
-2. `latestRulesetIdOf[projectId]` updated
-
-**Events**: `QueueRulesets(rulesetId, projectId, memo, caller)`, `RulesetQueued(rulesetId, projectId, ...)`
-
-**Edge cases**:
-- Empty array reverts (`RulesetsArrayEmpty`)
-- `reservedPercent > 10,000` reverts
-- `cashOutTaxRate > 10,000` reverts
-- `weight > type(uint112).max` reverts
-- `duration > type(uint32).max` reverts
-- `mustStartAtOrAfter + duration > type(uint48).max` reverts
-- If `mustStartAtOrAfter = 0`, it defaults to `block.timestamp`
-- If `rulesetId` collides with current timestamp, it is incremented by 1
-- Approval hook address is validated: must have code, must support `IJBRulesetApprovalHook` interface
-- Queued rulesets take effect after the current ruleset expires (or immediately for `duration = 0`)
-
----
-
-## 9. Set Splits
-
-**Entry point**: `JBController.setSplitGroupsOf(uint256 projectId, uint256 rulesetId, JBSplitGroup[] splitGroups)`
-
-**Who can call**: Project owner or address with `SET_SPLIT_GROUPS` permission. Alternatively, a contract whose address matches the lower 160 bits of a `groupId` can set that group directly -- but only if the upper 96 bits of the `groupId` are non-zero (bare-address groupIds are protocol-reserved for terminal payout groups).
-
-**Parameters**:
-- `projectId` -- Target project
-- `rulesetId` -- The ruleset ID the splits apply to. Use `0` for default/fallback splits.
-- `splitGroups` -- Array of `JBSplitGroup` structs, each containing a `groupId` and `JBSplit[]`
-
-**State changes**:
-1. `JBSplits` stores the new split groups for the project/ruleset/group combination
-2. Locked splits from existing configuration must be preserved (validated by `JBSplits`)
-
-**Events**: `SetSplit(projectId, rulesetId, groupId, split, caller)` per split (emitted by `JBSplits`, not `JBController`)
-
-**Edge cases**:
-- Locked splits (`lockedUntil > block.timestamp`) cannot be removed or modified
-- If no splits set for a rulesetId, `splitsOf()` falls back to `rulesetId = 0` (default splits)
-- If no default splits either, all payouts/reserved tokens go to project owner
-- Split `percent` values are out of `SPLITS_TOTAL_PERCENT` (1,000,000,000)
-- Payout splits use `groupId = uint256(uint160(token))`, reserved token splits use `groupId = 1` (`JBSplitGroupIds.RESERVED_TOKENS`)
-
----
-
-## 10. Migrate Terminal
-
-**Entry point**: `JBMultiTerminal.migrateBalanceOf(uint256 projectId, address token, IJBTerminal to)`
-
-**Who can call**: Project owner or address with `MIGRATE_TERMINAL` permission.
-
-**Parameters**:
-- `projectId` -- Project being migrated
-- `token` -- Token balance to migrate
-- `to` -- Destination terminal
-
-**State changes**:
-1. `_feeFreeSurplusOf[projectId][token]` cleared
-2. `JBTerminalStore.balanceOf[oldTerminal][projectId][token]` set to 0
-3. If destination is non-feeless: 2.5% protocol fee deducted from balance via `_takeFeeFrom`
-4. Remaining funds transferred to destination terminal via `to.addToBalanceOf()`
-5. Destination terminal records the added balance
-
-**Events**: `MigrateTerminal(projectId, token, to, amount, caller)`
-
-**Edge cases**:
-- Requires `allowTerminalMigration` in current ruleset
-- Destination terminal must have accounting context for the token (validated via `accountingContextForTokenOf`)
-- **Standard 2.5% protocol fee** is charged when migrating to a non-feeless terminal, consistent with all other fund egress. This also settles any `_feeFreeSurplusOf` liability.
-- **Held fees are NOT transferred** -- they remain in the old terminal. Held fees belong to the fee beneficiary (project #1), not the migrating project.
-- If balance is 0, no transfer occurs
-- This only migrates one token's balance. Must be called once per token.
-
----
-
-## 11. Migrate Controller
-
-**Entry point**: `JBDirectory.setControllerOf(uint256 projectId, IERC165 controller)`
-
-**Who can call**: Project owner, address with `SET_CONTROLLER` permission, or an address in `isAllowedToSetFirstController` (for first controller only). The current controller's ruleset must have `allowSetController` enabled.
-
-**Parameters**:
-- `projectId` -- The project being migrated
-- `controller` -- The new controller (must support `IERC165`)
-
-**Flow**:
-1. `JBDirectory.setControllerOf(projectId, newController)` is called
-2. If old controller exists AND new controller supports `IJBMigratable`: directory calls `newController.beforeReceiveMigrationFrom(oldController, projectId)`:
-   - Copies metadata URI from old controller (if it supports `IJBProjectUriRegistry`)
-   - Distributes pending reserved tokens from old controller (if it supports `IJBController` and has pending tokens)
-3. If old controller exists AND old controller supports `IJBMigratable`: directory calls `oldController.migrate(projectId, newController)`:
-   - Reverts if pending reserved tokens > 0 (must distribute first)
-4. Directory updates `controllerOf[projectId] = newController`
-5. If old controller exists AND new controller supports `IJBMigratable`: directory calls `newController.afterReceiveMigrationFrom(oldController, projectId)` (currently a no-op; verifies caller is the directory)
-
-**Events**: `Migrate(projectId, to, caller)` from old controller; `SetController(projectId, controller, caller)` from directory
-
-**Edge cases**:
-- `pendingReservedTokenBalanceOf[projectId] != 0` causes revert in `migrate()` -- reserved tokens must be distributed first
-- `beforeReceiveMigrationFrom` automatically distributes pending reserved tokens from the old controller
-- The old controller's `migrate()` runs while the directory still points to it (prevents reentrancy window)
-- First controller can be set by addresses in `isAllowedToSetFirstController` without owner permission
-
----
-
-## 12. Deploy ERC-20 for Project Tokens
-
-**Entry point**: `JBController.deployERC20For(uint256 projectId, string name, string symbol, bytes32 salt)`
-
-**Who can call**: Project owner or address with `DEPLOY_ERC20` permission.
-
-**Parameters**:
-- `projectId` -- Target project
-- `name` -- ERC-20 token name
-- `symbol` -- ERC-20 token symbol
-- `salt` -- For deterministic deployment (CREATE2). Pass `bytes32(0)` for non-deterministic.
-
-**State changes**:
-1. `JBTokens.deployERC20For()` clones `JBERC20` implementation via `Clones.clone()` (or `Clones.cloneDeterministic()` if salt provided)
-2. Clone's `initialize(name, symbol, owner=JBTokens)` is called
-3. `JBTokens.tokenOf[projectId]` set to the new token
-
-**Events**: `DeployERC20(projectId, deployer, salt, saltHash, caller)` from `JBController`, `DeployERC20(projectId, token, name, symbol, salt, caller)` from `JBTokens`
-
-**Edge cases**:
-- Can only be called once per project. If a token is already set, `JBTokens` reverts.
-- `salt` is hashed with `_msgSender()` to prevent front-running deterministic deployments
-- The clone's constructor sets invalid name/symbol; real values come from `initialize()`
-
----
-
-## 13. Claim Credits as ERC-20
-
-**Entry point**: `JBController.claimTokensFor(address holder, uint256 projectId, uint256 tokenCount, address beneficiary)`
-
-**Who can call**: The credit holder or address with `CLAIM_TOKENS` permission.
-
-**Parameters**:
-- `holder` -- Address whose credits to convert
-- `projectId` -- Target project
-- `tokenCount` -- Number of credits to convert to ERC-20
-- `beneficiary` -- Address to receive the ERC-20 tokens
-
-**State changes**:
-1. `JBTokens.creditBalanceOf[holder][projectId]` decreased by `tokenCount`
-2. ERC-20 tokens minted to `beneficiary` for `tokenCount`
-
-**Events**: `ClaimTokens(holder, projectId, creditBalance, count, beneficiary, caller)` (emitted by `JBTokens`)
-
-**Edge cases**:
-- Requires an ERC-20 token to be deployed for the project (reverts otherwise)
-- Credits and ERC-20 tokens are fungible -- this is a one-way conversion from internal credits to on-chain ERC-20
-- Does not require any ruleset flag (always allowed if ERC-20 exists)
-
----
-
-## 14. Process Held Fees
-
-**Entry point**: `JBMultiTerminal.processHeldFeesOf(uint256 projectId, address token, uint256 count)`
-
-**Who can call**: Anyone.
-
-**Parameters**:
-- `projectId` -- Project whose held fees to process
-- `token` -- Token the fees are denominated in
-- `count` -- Maximum number of held fees to process
-
-**State changes**:
-1. For each processable fee (unlocked, i.e., `unlockTimestamp <= block.timestamp`):
-   - Fee entry deleted from `_heldFeesOf` array
-   - `_nextHeldFeeIndexOf` incremented
-   - Fee amount sent to project #1's terminal via `_processFee` (try-catch)
-   - On failure: fee amount returned to project's balance
-2. If all fees processed: array and index are reset to 0
-
-**Events**: `ProcessFee(projectId, token, amount, wasHeld, beneficiary, caller)` per fee, or `FeeReverted(...)` on failure
-
-**Edge cases**:
-- Fees unlock after 28 days from when they were held
-- Processing stops at the first locked fee (fees are sequential)
-- Re-reads storage index each iteration (reentrancy-safe)
-- If fee terminal for project #1 does not exist for the token, `_processFee` reverts (caught by try-catch, returns to project balance)
-
----
-
-## 15. Add Price Feeds
-
-**Entry point**: `JBController.addPriceFeedFor(uint256 projectId, uint256 pricingCurrency, uint256 unitCurrency, IJBPriceFeed feed)`
-
-**Who can call**: Project owner or address with `ADD_PRICE_FEED` permission.
-
-**Parameters**:
-- `projectId` -- Project the feed applies to (0 for protocol-wide default, owner-only)
-- `pricingCurrency` -- Currency the feed's output is in
-- `unitCurrency` -- Currency being priced
-- `feed` -- The price feed contract address
-
-**State changes**:
-1. `JBPrices` stores the feed for the `(projectId, pricingCurrency, unitCurrency)` triple
-2. Feed is **immutable** once set -- cannot be replaced or removed
-
-**Events**: `AddPriceFeed(projectId, pricingCurrency, unitCurrency, feed, caller)` (emitted by `JBPrices`)
-
-**Edge cases**:
-- Requires `allowAddPriceFeed` in current ruleset
-- Protocol-wide defaults (`projectId = 0`) can only be set by the `JBPrices` owner
-- `JBPrices` auto-calculates inverse: if A->B exists, B->A is derived. If both explicit and inverse exist, explicit takes priority.
-- Lookup order: project-specific -> project-specific inverse -> default (projectId=0) -> default inverse
-
----
-
-## 16. Set Permissions
-
-**Entry point**: `JBPermissions.setPermissionsFor(address account, JBPermissionsData permissionsData)`
-
-**Who can call**: The `account` itself, or a ROOT operator for the project (with restrictions).
-
-**Parameters**:
-- `account` -- The account granting permissions
-- `permissionsData.operator` -- Address receiving the permissions
-- `permissionsData.projectId` -- Project scope (0 = wildcard, all projects)
-- `permissionsData.permissionIds` -- Array of `uint8` permission IDs to grant
-
-**State changes**:
-1. `permissionsOf[operator][account][projectId]` set to packed `uint256` bitmap
-
-**Events**: `OperatorPermissionsSet(operator, account, projectId, permissionIds, packed, caller)`
-
-**Edge cases**:
-- Permission ID 0 cannot be set (reserved, always `NoZeroPermission` revert)
-- ROOT (ID 1) cannot be set for wildcard `projectId = 0` (`CantSetRootPermissionForWildcardProject`)
-- ROOT operators can set non-ROOT permissions for others on their scoped project
-- ROOT operators CANNOT grant ROOT to other addresses
-- ROOT operators CANNOT set permissions for wildcard `projectId = 0`
-- Setting permissions replaces the entire bitmap (not additive) -- passing an empty array clears all permissions
-
----
-
-## 17. Transfer Project Ownership
-
-**Entry point**: `JBProjects.transferFrom(address from, address to, uint256 tokenId)` (standard ERC-721)
-
-**Who can call**: The current owner, an approved address, or an operator approved for all.
-
-**Parameters**:
-- `from` -- Current owner
-- `to` -- New owner
-- `tokenId` -- The project ID (same as the ERC-721 token ID)
-
-**State changes**:
-1. ERC-721 ownership transferred
-2. All `PROJECTS.ownerOf(projectId)` calls now return the new owner
-3. All permission checks that reference the owner now apply to the new owner
-
-**Events**: `Transfer(from, to, tokenId)` (standard ERC-721 event)
-
-**Edge cases**:
-- This is a standard ERC-721 transfer. All ERC-721 rules apply (approval, operator, etc.)
-- **Permissions are NOT transferred**. Existing operators retain their permissions scoped to the account that granted them (the old owner). The new owner must grant their own permissions.
-- The new owner immediately gets full control: queue rulesets, set terminals, set splits, etc.
-- Transferring to `address(0)` is prevented by OpenZeppelin's ERC-721 implementation
-
----
-
-## 18. Add to Balance (Without Minting)
-
-**Entry point**: `JBMultiTerminal.addToBalanceOf(uint256 projectId, address token, uint256 amount, bool shouldReturnHeldFees, string memo, bytes metadata)`
-
-**Who can call**: Anyone.
-
-**Parameters**:
-- `projectId` -- Project to add funds to
-- `token` -- Token to add
-- `amount` -- Amount to add (uses `msg.value` for native token)
-- `shouldReturnHeldFees` -- If true, uses the added amount to return held fees (reducing the fee burden)
-- `memo`, `metadata` -- Arbitrary data
-
-**State changes**:
-1. Tokens transferred to terminal
-2. If `shouldReturnHeldFees`: iterates held fees, returns fees proportional to amount added
-3. `JBTerminalStore.balanceOf[terminal][projectId][token]` incremented by `amount + returnedFees`
-
-**Events**: `AddToBalance(projectId, amount, returnedFees, memo, metadata, caller)`
-
-**Edge cases**:
-- Does NOT mint tokens -- purely adds to balance. This increases surplus, which increases cash out value for existing holders.
-- `shouldReturnHeldFees = true` partially or fully returns held fees. The returned fee amount is added to the project balance on top of the deposited amount.
-- Used by terminal migration (`migrateBalanceOf`) and split payouts (when `preferAddToBalance = true`)
-
----
-
-## 19. Transfer Credits
-
-**Entry point**: `JBController.transferCreditsFrom(address holder, uint256 projectId, address recipient, uint256 creditCount)`
-
-**Who can call**: The credit holder or address with `TRANSFER_CREDITS` permission.
-
-**Parameters**:
-- `holder` -- Address transferring credits
-- `projectId` -- Project whose credits are being transferred
-- `recipient` -- Address to receive credits
-- `creditCount` -- Number of credits to transfer
-
-**State changes**:
-1. `JBTokens.creditBalanceOf[holder][projectId]` decreased
-2. `JBTokens.creditBalanceOf[recipient][projectId]` increased
-
-**Events**: `TransferCredits(holder, projectId, recipient, count, caller)` (emitted by `JBTokens`)
-
-**Edge cases**:
-- Reverts if `pauseCreditTransfers` is set in current ruleset
-- Credits are internal -- they are NOT ERC-20 tokens. Use `claimTokensFor` to convert credits to ERC-20.
-- This only transfers credits, not ERC-20 tokens. ERC-20 tokens are transferred via standard ERC-20 `transfer`/`transferFrom`.
-
----
-
-## 20. Set Project URI
-
-**Entry point**: `JBController.setUriOf(uint256 projectId, string uri)`
-
-**Who can call**: Project owner or address with `SET_PROJECT_URI` permission.
-
-**Parameters**:
-- `projectId` -- Target project
-- `uri` -- Metadata URI (typically an IPFS hash)
-
-**State changes**: `uriOf[projectId] = uri`
-
-**Events**: `SetUri(projectId, uri, caller)`
-
-**Edge cases**:
-- Empty string is valid -- clears the metadata URI
-- No ruleset flag required (always allowed with permission)
-
----
-
-## 21. Set Custom Token
-
-**Entry point**: `JBController.setTokenFor(uint256 projectId, IJBToken token)`
-
-**Who can call**: Project owner or address with `SET_TOKEN` permission.
-
-**Parameters**:
-- `projectId` -- Target project
-- `token` -- The custom token contract (must implement `IJBToken`)
-
-**State changes**: `JBTokens.tokenOf[projectId] = token`
-
-**Events**: `SetToken(projectId, token, caller)` (emitted by `JBTokens`)
-
-**Edge cases**:
-- Requires `allowSetCustomToken` in current or upcoming ruleset
-- Can only be called if no token is currently set for the project
-- The token must conform to `IJBToken` interface (18 decimals required)
-
----
-
-## 22. Set Token Metadata
-
-**Entry point**: `JBController.setTokenMetadataOf(uint256 projectId, string name, string symbol)`
-
-**Who can call**: Project owner or address with `SET_TOKEN_METADATA` permission.
-
-**Parameters**:
-- `projectId` -- Target project
-- `name` -- New ERC-20 token name
-- `symbol` -- New ERC-20 token symbol
-
-**State changes**: Updates the ERC-20 token's name and symbol via `JBERC20.setMetadata()`
-
-**Events**: `SetTokenMetadata(projectId, name, symbol, caller)` (emitted by `JBTokens`)
-
-**Edge cases**:
-- Requires an ERC-20 token to be deployed for the project (reverts if no token set)
-- Only works with `JBERC20` clones (custom tokens that implement `IJBToken` may not support `setMetadata`)
-
----
-
-## 23. Update Ruleset Weight Cache
-
-**Entry point**: `JBRulesets.updateRulesetWeightCache(uint256 projectId, uint256 rulesetId)`
-
-**Who can call**: Anyone.
-
-**Parameters**:
-- `projectId` -- Target project
-- `rulesetId` -- The specific ruleset to update cache for
-
-**State changes**:
-1. `_weightCacheOf[projectId][rulesetId].weight` updated to current decayed weight
-2. `_weightCacheOf[projectId][rulesetId].weightCutMultiple` updated
-
-**Events**: `WeightCacheUpdated(projectId, weight, weightCutMultiple, caller)`
-
-**Edge cases**:
-- Required for projects with >20,000 cycles (otherwise `currentOf()` reverts with `WeightCacheRequired`)
-- Advances the cache by at most `_WEIGHT_CUT_MULTIPLE_CACHE_LOOKUP_THRESHOLD` (20,000) cycles per call
-- Multiple calls needed to fully catch up for very large cycle gaps
-- No-op if `duration == 0` or `weightCutPercent == 0`
-
----
-
-## 24. Add Accounting Contexts
-
-**Entry point**: `JBMultiTerminal.addAccountingContextsFor(uint256 projectId, JBAccountingContext[] accountingContexts)`
-
-**Who can call**: Project owner, address with `ADD_ACCOUNTING_CONTEXTS` permission, or the project's controller.
-
-**Parameters**:
-- `projectId` -- Target project
-- `accountingContexts` -- Array of `JBAccountingContext` structs, each specifying a token address, decimals, and currency
-
-**State changes**:
-1. For each context: validates token decimals, stores `_accountingContextForTokenOf[projectId][token]`
-2. Appends to `_accountingContextsOf[projectId]` array
-
-**Events**: `SetAccountingContext(projectId, context, caller)` per token
-
-**Edge cases**:
-- Requires `allowAddAccountingContext` in current ruleset (if ruleset exists)
-- Token cannot be added twice (`AccountingContextAlreadySet`)
-- Currency must be non-zero (`ZeroAccountingContextCurrency`)
-- For non-native tokens: decimals are validated against the token's `decimals()` function. Tokens that revert on `decimals()` bypass validation (caller responsible).
+- Use [nana-permission-ids-v6](../nana-permission-ids-v6/USER_JOURNEYS.md) for the shared permission vocabulary that downstream repos import.
+- Use [nana-721-hook-v6](../nana-721-hook-v6/USER_JOURNEYS.md), [nana-router-terminal-v6](../nana-router-terminal-v6/USER_JOURNEYS.md), and [nana-buyback-hook-v6](../nana-buyback-hook-v6/USER_JOURNEYS.md) for opinionated layers on top of the core terminal and ruleset surfaces.