@bananapus/core-v6 0.0.34 → 0.0.35

package/USER_JOURNEYS.md

@@ -1,6 +1,12 @@
 # User Journeys
 
-## Who This Repo Serves
+## Repo Purpose
+
+This repo is the canonical Juicebox V6 runtime surface.
+It owns project identity, rulesets, terminal execution, treasury accounting, permissions, price feeds, and migration
+paths. Most other V6 repos wrap or extend this behavior rather than replacing it.
+
+## Primary Actors
 
 - founders launching and evolving Juicebox projects
 - supporters paying projects in the asset a terminal accepts
@@ -8,109 +14,203 @@
 - operators managing permissions, splits, fund access limits, and rulesets
 - integrators wiring hooks, terminals, price feeds, and migrations into the canonical protocol surface
 
+## Key Surfaces
+
+- `JBController`: project launch, ruleset queueing, token setup, splits, and controller migration
+- `JBMultiTerminal`: pay, payout, allowance, preview, and cash-out entrypoint
+- `JBTerminalStore`: balance, surplus, fee, and reclaim accounting
+- `JBDirectory`: controller and terminal routing
+- `JBPermissions`: packed operator-permission registry
+- `JBProjects`, `JBRulesets`, `JBPrices`, `JBFundAccessLimits`, `JBSplits`, `JBTokens`: core state and helper surfaces
+
 ## Journey 1: Launch A Project With The Right Initial Shape
 
-**Starting state:** you know who should own the project, which terminals it should use, and what the first ruleset should allow.
+**Actor:** founder, deployer, or protocol integrator.
 
-**Success:** the project NFT exists, the initial ruleset is active, accepted terminals are installed, and downstream hooks or splits can begin working immediately.
+**Intent:** create a project with the right owner, terminal, ruleset, and hook assumptions from block zero.
 
-**Flow**
+**Preconditions**
+- the team knows who should own the project, which terminals it should use, and what the first ruleset should allow
+
+**Main 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.
 
-**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.
+**Failure Modes**
+- accounting contexts do not match the intended terminal asset
+- hook metadata or split assumptions are invalid at launch
+- ownership or permission assumptions are wrong and expensive to repair later
+
+**Postconditions**
+- the project NFT exists, the initial ruleset is active, accepted terminals are installed, and downstream hooks or splits can begin working immediately
 
 ## Journey 2: Accept A Payment And Issue The Right Token Exposure
 
-**Starting state:** the project has an active ruleset and a terminal that accepts the payer's asset.
+**Actor:** payer or integration paying on a user's behalf.
+
+**Intent:** settle a payment through the canonical terminal path and issue the correct token exposure.
 
-**Success:** treasury balances increase, hooks run in the right order, and the beneficiary receives credits or ERC-20 tokens consistent with the ruleset.
+**Preconditions**
+- the project has an active ruleset and a terminal that accepts the payer's asset
 
-**Flow**
+**Main 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.
 
-**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.
+**Failure Modes**
+- payments are paused or the token is unsupported for the target accounting context
+- fee-on-transfer behavior or price-feed assumptions break the intended issuance path
+- hooks add side effects the payer or integrator did not account for
+
+**Postconditions**
+- treasury balances increase, hooks run in the right order, and the beneficiary receives credits or ERC-20 tokens consistent with the ruleset
 
 ## Journey 3: Turn Credits Into ERC-20 Tokens Once A Project Wants A Transferable Token
 
-**Starting state:** users already have project token credits and the project now wants an ERC-20 representation.
+**Actor:** holder or operator acting for a holder.
+
+**Intent:** convert non-transferable project credits into ERC-20 balances once the project exposes a token.
 
-**Success:** the project deploys or installs its ERC-20 token and holders can claim credits into transferable balances.
+**Preconditions**
+- users already have project token credits
+- the project now wants an ERC-20 representation
 
-**Flow**
+**Main 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.
 
+**Failure Modes**
+- the wrong token is installed for the project
+- integrations assume credits are automatically ERC-20 balances after token installation
+
+**Postconditions**
+- the project deploys or installs its ERC-20 token and holders can claim credits into transferable balances
+
 ## Journey 4: Distribute Treasury Funds Through Governed Paths
 
-**Starting state:** the project has terminal balances and the owner wants payouts or allowance-based withdrawals.
+**Actor:** owner or authorized operator.
+
+**Intent:** move value out of the treasury through configured payouts or allowance surfaces.
 
-**Success:** treasury value leaves only through configured limits, recipients, and fee logic instead of arbitrary admin withdrawals.
+**Preconditions**
+- the project has terminal balances
+- the caller is allowed to use payout or allowance paths
 
-**Flow**
+**Main 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.
 
-**Failure cases that matter:** stale split expectations, exceeding access limits, downstream hook failures, and assuming allowance withdrawals behave like payouts when fee treatment differs.
+**Failure Modes**
+- splits or access limits no longer match operator expectations
+- downstream hook execution fails during payout fanout
+- operators assume allowance withdrawals behave exactly like payouts when fee treatment differs
+
+**Postconditions**
+- treasury value leaves only through configured limits, recipients, and fee logic instead of arbitrary admin withdrawals
 
 ## Journey 5: Let Holders Cash Out Against Surplus
 
-**Starting state:** a holder owns project token exposure and the project has reclaimable surplus in some terminal.
+**Actor:** holder or integrator acting for a holder.
 
-**Success:** the holder burns the intended amount of token exposure and receives the correct reclaim amount under the current ruleset.
+**Intent:** exit project-token exposure against available terminal surplus.
 
-**Flow**
+**Preconditions**
+- a holder owns project token exposure
+- the project has reclaimable surplus in some terminal
+
+**Main 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.
 
-**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.
+**Failure Modes**
+- fee-free or custom hook paths produce different outcomes than the holder expected
+- preview-versus-execution drift appears under volatile routing or multi-terminal liquidity
+- users misread multi-terminal surplus as one homogeneous pool
+
+**Postconditions**
+- the holder burns the intended amount of token exposure and receives the correct reclaim amount under the current ruleset
 
 ## Journey 6: Queue New Rulesets Without Migrating The Project
 
-**Starting state:** the project is live and future economics need to change.
+**Actor:** owner or authorized operator.
+
+**Intent:** change future project economics without changing the project's identity or existing balances.
 
-**Success:** the next ruleset activates on schedule while the project keeps the same identity, treasury, and downstream integrations.
+**Preconditions**
+- the project is live and future economics need to change
 
-**Flow**
+**Main 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.
 
-**Failure cases that matter:** forgetting approval hooks, queueing incompatible metadata for installed hooks, and assuming a ruleset change can retroactively repair prior accounting.
+**Failure Modes**
+- approval-hook requirements are forgotten or misunderstood
+- queued metadata is incompatible with installed hooks
+- teams assume a ruleset change can retroactively fix prior accounting
+
+**Postconditions**
+- the next ruleset activates on schedule while the project keeps the same identity, treasury, and downstream integrations
 
 ## Journey 7: Migrate A Project To New Terminal Or Controller Surfaces Deliberately
 
-**Starting state:** the project needs to move to a new terminal or controller path without pretending historical balances and routing do not exist.
+**Actor:** owner or migration operator.
+
+**Intent:** move a live project to new terminal or controller surfaces without corrupting balances, permissions, or routing history.
 
-**Success:** migration uses the protocol's explicit surfaces so balances, permissions, and future routing stay coherent.
+**Preconditions**
+- the project needs to move to a new terminal or controller path
+- the destination surface is understood and intended
 
-**Flow**
+**Main 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.
 
+**Failure Modes**
+- migration targets are wrong or only partially configured
+- operators manually repoint routing without using the protocol's migration surfaces
+
+**Postconditions**
+- balances, permissions, and future routing stay coherent after migration
+
 ## Journey 8: Hand Off Authority Without Handing Out Root Access
 
-**Starting state:** the project owner wants operators, delegates, or automation to manage only specific surfaces.
+**Actor:** project owner.
+
+**Intent:** delegate project operations narrowly instead of transferring blanket control.
 
-**Success:** permissions are narrow, auditable, and scoped to the actions the operator actually needs.
+**Preconditions**
+- the owner wants operators, delegates, or automation to manage only specific surfaces
 
-**Flow**
+**Main 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.
 
+**Failure Modes**
+- operators receive permissions broader than they need
+- auditors assume downstream access still depends only on project ownership
+
+**Postconditions**
+- permissions are narrow, auditable, and scoped to the actions the operator actually needs
+
+## Trust Boundaries
+
+- `JBTerminalStore` is the accounting truth for balances, surplus, fees, and reclaim behavior
+- hooks, approval hooks, pay hooks, and cash-out hooks are trusted extension surfaces, not cosmetic plugins
+- price feeds and directory routing are critical external-context surfaces inherited by many downstream repos
+
 ## Hand-Offs
 
 - Use [nana-permission-ids-v6](../nana-permission-ids-v6/USER_JOURNEYS.md) for the shared permission vocabulary that downstream repos import.

package/foundry.toml

@@ -16,6 +16,8 @@ fail_on_revert = false
 [rpc_endpoints]
 ethereum = "${RPC_ETHEREUM_MAINNET}"
 
+[lint]
+exclude_lints = ["pascal-case-struct", "mixed-case-variable"]
 [fmt]
 number_underscore = "thousands"
 multiline_func_header = "all"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/core-v6",
-  "version": "0.0.34",
+  "version": "0.0.35",
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/JBERC20.sol

@@ -40,7 +40,6 @@ contract JBERC20 is ERC20Votes, ERC20Permit, JBPermissioned, IERC1271, IJBToken
 
     /// @notice The JBTokens contract that owns this token.
     /// @dev Set via `initialize` because JBERC20 is deployed before JBTokens (circular dependency).
-    // forge-lint: disable-next-line(mixed-case-variable)
     IJBTokens public TOKENS;
 
     //*********************************************************************//

package/src/structs/JBAccountingContext.sol

@@ -5,7 +5,6 @@ pragma solidity ^0.8.0;
 /// @custom:member decimals The number of decimals expected in that token's fixed point accounting.
 /// @custom:member currency The currency that the token is priced in terms of. By convention, this is
 /// `uint32(uint160(tokenAddress))` for tokens, or a constant ID from e.g. `JBCurrencyIds` for other currencies.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct JBAccountingContext {
     address token;
     uint8 decimals;

package/src/structs/JBAfterCashOutRecordedContext.sol

@@ -16,7 +16,6 @@ import {JBTokenAmount} from "./JBTokenAmount.sol";
 /// @custom:member beneficiary The address the reclaimed amount will be sent to.
 /// @custom:member hookMetadata Extra data specified by the data hook, which is sent to the cash out hook.
 /// @custom:member cashOutMetadata Extra data specified by the account cashing out, which is sent to the cash out hook.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct JBAfterCashOutRecordedContext {
     address holder;
     uint256 projectId;

package/src/structs/JBAfterPayRecordedContext.sol

@@ -15,7 +15,6 @@ import {JBTokenAmount} from "./JBTokenAmount.sol";
 /// @custom:member beneficiary The address which receives any tokens this payment yields.
 /// @custom:member hookMetadata Extra data specified by the data hook, which is sent to the pay hook.
 /// @custom:member payerMetadata Extra data specified by the payer, which is sent to the pay hook.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct JBAfterPayRecordedContext {
     address payer;
     uint256 projectId;

package/src/structs/JBBeforeCashOutRecordedContext.sol

@@ -20,7 +20,6 @@ import {JBTokenAmount} from "./JBTokenAmount.sol";
 /// that charge their own fees — they can skip fees when value stays in the protocol (e.g. project-to-project
 /// routing).
 /// @custom:member metadata Extra data provided by the casher.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct JBBeforeCashOutRecordedContext {
     address terminal;
     address holder;

package/src/structs/JBBeforePayRecordedContext.sol

@@ -15,7 +15,6 @@ import {JBTokenAmount} from "./JBTokenAmount.sol";
 /// @custom:member weight The weight of the ruleset during which the payment is being made.
 /// @custom:member reservedPercent The reserved percent of the ruleset the payment is being made during.
 /// @custom:member metadata Extra data specified by the payer.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct JBBeforePayRecordedContext {
     address terminal;
     address payer;

package/src/structs/JBCashOutHookSpecification.sol

@@ -9,7 +9,6 @@ import {IJBCashOutHook} from "../interfaces/IJBCashOutHook.sol";
 /// @custom:member noop A flag indicating if the hook callback should be skipped.
 /// @custom:member amount The amount to send to the hook.
 /// @custom:member metadata Metadata to pass to the hook.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct JBCashOutHookSpecification {
     IJBCashOutHook hook;
     bool noop;

package/src/structs/JBCurrencyAmount.sol

@@ -4,7 +4,6 @@ pragma solidity ^0.8.0;
 /// @custom:member amount The amount of the currency.
 /// @custom:member currency The currency. By convention, this is `uint32(uint160(tokenAddress))` for tokens, or a
 /// constant ID from e.g. `JBCurrencyIds` for other currencies.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct JBCurrencyAmount {
     uint224 amount;
     uint32 currency;

package/src/structs/JBFee.sol

@@ -5,7 +5,6 @@ pragma solidity ^0.8.0;
 /// decimals as the terminal in which this struct was created.
 /// @custom:member beneficiary The address that will receive the tokens that are minted as a result of the fee payment.
 /// @custom:member unlockTimestamp The timestamp at which the fee is unlocked and can be processed.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct JBFee {
     uint256 amount;
     address beneficiary;

package/src/structs/JBFundAccessLimitGroup.sol

@@ -20,7 +20,6 @@ import {JBCurrencyAmount} from "./JBCurrencyAmount.sol";
 /// @custom:member surplusAllowances An array of surplus allowances. The surplus allowances cumulatively dictates the
 /// maximum value of `token`s a project can pay out from its surplus (balance less payouts) in a terminal during a
 /// ruleset. Each surplus allowance can have a unique currency and amount.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct JBFundAccessLimitGroup {
     address terminal;
     address token;

package/src/structs/JBPayHookSpecification.sol

@@ -9,7 +9,6 @@ import {IJBPayHook} from "../interfaces/IJBPayHook.sol";
 /// @custom:member noop A flag indicating if the hook callback should be skipped.
 /// @custom:member amount The amount to send to the hook.
 /// @custom:member metadata Metadata to pass the hook.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct JBPayHookSpecification {
     IJBPayHook hook;
     bool noop;

package/src/structs/JBPermissionsData.sol

@@ -6,7 +6,6 @@ pragma solidity ^0.8.0;
 /// permissions under this project's scope. An ID of 0 is a wildcard, which gives an operator permissions across all
 /// projects.
 /// @custom:member permissionIds The IDs of the permissions being given. See the `JBPermissionIds` library.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct JBPermissionsData {
     address operator;
     uint64 projectId;

package/src/structs/JBRuleset.sol

@@ -29,7 +29,6 @@ import {IJBRulesetApprovalHook} from "./../interfaces/IJBRulesetApprovalHook.sol
 /// ruleset is rejected, it won't go into effect. An approval hook can be used to create rules which dictate how a
 /// project owner can change their ruleset over time.
 /// @custom:member metadata Extra data associated with a ruleset which can be used by other contracts.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct JBRuleset {
     uint48 cycleNumber;
     uint48 id;

package/src/structs/JBRulesetConfig.sol

@@ -31,7 +31,6 @@ import {JBSplitGroup} from "./JBSplitGroup.sol";
 /// its balance in each payment terminal while the ruleset is active. Amounts are fixed point numbers using the same
 /// number of decimals as the corresponding terminal. The `_payoutLimit` and `_surplusAllowance` parameters must fit in
 /// a `uint232`.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct JBRulesetConfig {
     uint48 mustStartAtOrAfter;
     uint32 duration;

package/src/structs/JBRulesetMetadata.sol

@@ -33,7 +33,6 @@ pragma solidity ^0.8.0;
 /// @custom:member dataHook The data hook to use during this ruleset.
 /// @custom:member metadata Metadata of the metadata, only the 14 least significant bits can be used, the 2 most
 /// significant bits are disregarded.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct JBRulesetMetadata {
     uint16 reservedPercent;
     uint16 cashOutTaxRate;

package/src/structs/JBRulesetWeightCache.sol

@@ -3,7 +3,6 @@ pragma solidity ^0.8.0;
 
 /// @custom:member weight The cached weight value.
 /// @custom:member weightCutMultiple The weight cut multiple that produces the given weight.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct JBRulesetWeightCache {
     uint112 weight;
     uint168 weightCutMultiple;

package/src/structs/JBRulesetWithMetadata.sol

@@ -6,7 +6,6 @@ import {JBRulesetMetadata} from "./JBRulesetMetadata.sol";
 
 /// @custom:member ruleset The ruleset.
 /// @custom:member metadata The ruleset's metadata.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct JBRulesetWithMetadata {
     JBRuleset ruleset;
     JBRulesetMetadata metadata;

package/src/structs/JBSingleAllowance.sol

@@ -7,7 +7,6 @@ pragma solidity ^0.8.0;
 /// @custom:member nonce An incrementing value indexed per owner,token,and spender for each signature.
 /// @custom:member signature The signature over the permit data. Supports EOA signatures, compact signatures defined by
 /// EIP-2098, and contract signatures defined by EIP-1271.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct JBSingleAllowance {
     uint256 sigDeadline;
     uint160 amount;

package/src/structs/JBSplit.sol

@@ -30,7 +30,6 @@ import {IJBSplitHook} from "./../interfaces/IJBSplitHook.sol";
 /// preserve those splits at the governance/configuration layer.
 /// @custom:member hook A contract which will receive this split's tokens and properties, and can define custom
 /// behavior.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct JBSplit {
     uint32 percent;
     uint64 projectId;

package/src/structs/JBSplitGroup.sol

@@ -6,7 +6,6 @@ import {JBSplit} from "./JBSplit.sol";
 /// @custom:member groupId An identifier for the group. By convention, this ID is `uint256(uint160(tokenAddress))` for
 /// payouts and `1` for reserved tokens.
 /// @custom:member splits The splits in the group.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct JBSplitGroup {
     uint256 groupId;
     JBSplit[] splits;

package/src/structs/JBSplitHookContext.sol

@@ -10,7 +10,6 @@ import {JBSplit} from "./JBSplit.sol";
 /// @custom:member groupId The group the split belongs to. By convention, this ID is `uint256(uint160(tokenAddress))`
 /// for payouts and `1` for reserved tokens.
 /// @custom:member split The split which specified the hook.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct JBSplitHookContext {
     address token;
     uint256 amount;

package/src/structs/JBTerminalConfig.sol

@@ -6,7 +6,6 @@ import {IJBTerminal} from "./../interfaces/IJBTerminal.sol";
 
 /// @custom:member terminal The terminal to configure.
 /// @custom:member accountingContextsToAccept The accounting contexts to accept from the terminal.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct JBTerminalConfig {
     IJBTerminal terminal;
     JBAccountingContext[] accountingContextsToAccept;

package/src/structs/JBTokenAmount.sol

@@ -6,7 +6,6 @@ pragma solidity ^0.8.0;
 /// @custom:member currency The currency. By convention, this is `uint32(uint160(tokenAddress))` for tokens, or a
 /// constant ID from e.g. `JBCurrencyIds` for other currencies.
 /// @custom:member value The amount of tokens that was paid, as a fixed point number.
-// forge-lint: disable-next-line(pascal-case-struct)
 struct JBTokenAmount {
     address token;
     uint8 decimals;