@bananapus/721-hook-v6 0.0.10 → 0.0.12

package/SKILLS.md

@@ -21,11 +21,11 @@ Tiered ERC-721 NFT hook for Juicebox V6 that mints NFTs when a project is paid a
 
 | Function | Contract | What it does |
 |----------|----------|--------------|
-| `initialize(projectId, name, symbol, baseUri, tokenUriResolver, contractUri, tiersConfig, flags)` | `JB721TiersHook` | One-time setup for a cloned hook instance. Stores pricing context (currency, decimals, prices contract packed into uint256), records tiers and flags in the store. Validates `decimals <= 18`. |
+| `initialize(projectId, name, symbol, baseUri, tokenUriResolver, contractUri, tiersConfig, flags)` | `JB721TiersHook` | One-time setup for a cloned hook instance. Stores pricing context (currency, decimals, prices contract packed into uint256), records tiers and flags in the store. Registers any configured tier splits in `JBSplits` via `SPLITS.setSplitGroupsOf`. Validates `decimals <= 18`. |
 | `afterPayRecordedWith(context)` | `JB721Hook` | Called by terminal after payment. Validates caller is a project terminal, delegates to virtual `_processPayment`. |
 | `_processPayment(context)` | `JB721TiersHook` | Normalizes payment value via pricing context, decodes payer metadata for tier IDs to mint, calls `_mintAll`, manages pay credits for overspending. Distributes tier split funds via `JB721TiersHookLib.distributeAll` if split amounts were forwarded. |
 | `afterCashOutRecordedWith(context)` | `JB721Hook` | Called by terminal during cash out. Decodes token IDs from metadata, validates ownership, burns NFTs, delegates to virtual `_didBurn`. Reverts if `msg.value != 0`. |
-| `beforePayRecordedWith(context)` | `JB721TiersHook` | Data hook: returns original weight, calculates per-tier split amounts via `JB721TiersHookLib.calculateSplitAmounts`, and sets this contract as the pay hook with the total split amount forwarded. |
+| `beforePayRecordedWith(context)` | `JB721TiersHook` | Data hook: calculates per-tier split amounts via `JB721TiersHookLib.calculateSplitAmounts`, adjusts the weight proportionally so the terminal only mints tokens for the amount that actually enters the project (i.e., `weight = mulDiv(context.weight, amount - totalSplitAmount, amount)`), and sets this contract as the pay hook with the total split amount forwarded. If no splits, returns original weight unchanged. If splits consume the entire payment, returns weight 0. If the `issueTokensForSplits` flag is set, returns the full `context.weight` regardless of splits. |
 | `beforeCashOutRecordedWith(context)` | `JB721Hook` | Data hook: calculates `cashOutCount` (via virtual `cashOutWeightOf`) and `totalSupply` (via virtual `totalCashOutWeight`). Rejects if fungible tokens are also being cashed out. |
 | `adjustTiers(tiersToAdd, tierIdsToRemove)` | `JB721TiersHook` | Owner-only. Adds/removes tiers via `JB721TiersHookLib.adjustTiersFor` (DELEGATECALL). Requires `ADJUST_721_TIERS` permission. Registers tier splits in `JBSplits` if configured. |
 | `mintFor(tierIds, beneficiary)` | `JB721TiersHook` | Owner-only manual mint. Requires `MINT_721` permission. Passes `amount: type(uint256).max` and `isOwnerMint: true` to force the mint. |
@@ -60,8 +60,8 @@ Tiered ERC-721 NFT hook for Juicebox V6 that mints NFTs when a project is paid a
 | `votingUnitsOf(hook, account)` | `JB721TiersHookStore` | Returns total voting units for an address across all tiers. Uses custom `votingUnits` if `useVotingUnits` is set, otherwise uses tier price. |
 | `tierVotingUnitsOf(hook, account, tierId)` | `JB721TiersHookStore` | Returns voting units for an address within a specific tier. |
 | `calculateSplitAmounts(store, hook, metadataIdTarget, metadata)` | `JB721TiersHookLib` | Called in `beforePayRecordedWith`. Decodes tier IDs from payer metadata, looks up each tier's `splitPercent`, calculates `mulDiv(price, splitPercent, SPLITS_TOTAL_PERCENT)` per tier, returns `totalSplitAmount` (forwarded to hook as `amount`) and encoded `hookMetadata` (tier IDs + amounts). |
-| `distributeAll(directory, projectId, hookAddress, token, encodedSplitData)` | `JB721TiersHookLib` | Called in `afterPayRecordedWith`. Decodes per-tier amounts, looks up each tier's splits from `JBSplits` by group ID (`hookAddress | (tierId << 160)`), distributes to split recipients. Leftover goes to project balance via `addToBalance`. |
-| `adjustTiersFor(store, directory, projectId, hookAddress, caller, tiersToAdd, tierIdsToRemove)` | `JB721TiersHookLib` | Called via DELEGATECALL from `adjustTiers`. Removes tiers, adds tiers, emits events, and registers any configured splits in `JBSplits` via the project's controller. |
+| `distributeAll(directory, splits, projectId, hookAddress, token, encodedSplitData)` | `JB721TiersHookLib` | Called in `afterPayRecordedWith`. Decodes per-tier amounts, looks up each tier's splits from `JBSplits` by group ID (`hookAddress | (tierId << 160)`), distributes to split recipients. Leftover goes to project balance via `addToBalance`. |
+| `adjustTiersFor(store, splits, projectId, hookAddress, caller, tiersToAdd, tierIdsToRemove)` | `JB721TiersHookLib` | Called via DELEGATECALL from `adjustTiers`. Removes tiers, adds tiers, emits events, and registers any configured splits directly in `JBSplits`. |
 | `normalizePaymentValue(packedPricingContext, projectId, amountValue, amountCurrency, amountDecimals)` | `JB721TiersHookLib` | Converts a payment value to the hook's pricing currency using `JBPrices`. Returns `(0, false)` if currencies differ and no prices contract is set. |
 | `resolveTokenURI(store, hook, baseUri, tokenId)` | `JB721TiersHookLib` | Resolves token URI: checks for custom `tokenUriResolver` first, otherwise decodes IPFS URI via `JBIpfsDecoder`. |
 
@@ -69,7 +69,7 @@ Tiered ERC-721 NFT hook for Juicebox V6 that mints NFTs when a project is paid a
 
 | Dependency | Import | Used For |
 |------------|--------|----------|
-| `@bananapus/core-v6` | `IJBDirectory`, `IJBRulesets`, `IJBPrices`, `IJBController`, `IJBTerminal`, `IJBSplits`, `JBRuleset`, `JBRulesetMetadata`, `JBAfterPayRecordedContext`, `JBBeforeCashOutRecordedContext`, `JBSplit`, `JBSplitGroup`, `JBConstants`, etc. | Terminal validation, ruleset metadata, pricing, payment/cash-out contexts, splits |
+| `@bananapus/core-v6` | `IJBDirectory`, `IJBRulesets`, `IJBPrices`, `IJBSplits`, `IJBTerminal`, `JBRuleset`, `JBRulesetMetadata`, `JBAfterPayRecordedContext`, `JBBeforeCashOutRecordedContext`, `JBSplit`, `JBSplitGroup`, `JBConstants`, etc. | Terminal validation, ruleset metadata, pricing, payment/cash-out contexts, splits |
 | `@bananapus/ownable-v6` | `JBOwnable` | Project-based ownership for the hook (ownership can be transferred to a project NFT) |
 | `@bananapus/permission-ids-v6` | `JBPermissionIds` | Permission IDs: `ADJUST_721_TIERS`, `MINT_721`, `SET_721_METADATA`, `SET_721_DISCOUNT_PERCENT`, `QUEUE_RULESETS`, `SET_TERMINALS` |
 | `@bananapus/address-registry-v6` | `IJBAddressRegistry` | Registering deployed hook clones |
@@ -86,7 +86,7 @@ Tiered ERC-721 NFT hook for Juicebox V6 that mints NFTs when a project is paid a
 | `JBStored721Tier` | `uint104 price`, `uint32 remainingSupply`, `uint32 initialSupply`, `uint32 splitPercent`, `uint24 category`, `uint8 discountPercent`, `uint16 reserveFrequency`, `uint8 packedBools` (allowOwnerMint, transfersPausable, useVotingUnits, cannotBeRemoved, cannotIncreaseDiscountPercent) | Internal storage in `JB721TiersHookStore`. Voting units stored separately in `_tierVotingUnitsOf` when `useVotingUnits` is true. |
 | `JB721InitTiersConfig` | `JB721TierConfig[] tiers`, `uint32 currency`, `uint8 decimals`, `IJBPrices prices` | `initialize` -- defines tiers and pricing context |
 | `JBDeploy721TiersHookConfig` | `string name`, `string symbol`, `string baseUri`, `IJB721TokenUriResolver tokenUriResolver`, `string contractUri`, `JB721InitTiersConfig tiersConfig`, `address reserveBeneficiary`, `JB721TiersHookFlags flags` | `deployHookFor`, `launchProjectFor` |
-| `JB721TiersHookFlags` | `bool noNewTiersWithReserves`, `bool noNewTiersWithVotes`, `bool noNewTiersWithOwnerMinting`, `bool preventOverspending` | `initialize`, `recordFlags` |
+| `JB721TiersHookFlags` | `bool noNewTiersWithReserves`, `bool noNewTiersWithVotes`, `bool noNewTiersWithOwnerMinting`, `bool preventOverspending`, `bool issueTokensForSplits` | `initialize`, `recordFlags` |
 | `JB721TiersRulesetMetadata` | `bool pauseTransfers`, `bool pauseMintPendingReserves` | Packed into `JBRulesetMetadata.metadata` per-ruleset (bit 0 = pauseTransfers, bit 1 = pauseMintPendingReserves) |
 | `JBPayDataHookRulesetConfig` | `uint48 mustStartAtOrAfter`, `uint32 duration`, `uint112 weight`, `uint32 weightCutPercent`, `IJBRulesetApprovalHook approvalHook`, `JBPayDataHookRulesetMetadata metadata`, `JBSplitGroup[] splitGroups`, `JBFundAccessLimitGroup[] fundAccessLimitGroups` | `JB721TiersHookProjectDeployer` -- wraps core ruleset config with `useDataHookForPay: true` hardcoded |
 | `JBPayDataHookRulesetMetadata` | Same as `JBRulesetMetadata` minus `allowSetCustomToken` (hardcoded false) and `useDataHookForPay` (hardcoded true) and `dataHook` (set to deployed hook). Includes `ownerMustSendPayouts`. | `launchProjectFor`, `launchRulesetsFor`, `queueRulesetsOf` |
@@ -137,14 +137,14 @@ Each tier has configurable voting power:
 
 - Each tier can route a percentage of its mint price to configured split recipients. The `splitPercent` field (out of `JBConstants.SPLITS_TOTAL_PERCENT` = 1,000,000,000) determines how much of the price is forwarded.
 - Split recipients are stored in `JBSplits` using group IDs computed as `uint256(uint160(hookAddress)) | (uint256(tierId) << 160)`.
-- Splits are registered via `JB721TiersHookLib._setSplitGroupsFor` when tiers with `splits` are added.
-- In `beforePayRecordedWith`, `calculateSplitAmounts` decodes tier IDs from payer metadata, computes `mulDiv(price, splitPercent, SPLITS_TOTAL_PERCENT)` per tier, and returns the total to be forwarded to the hook.
+- Splits are registered in `JBSplits` both during `initialize()` (for tiers included at launch) and during `adjustTiers()` (for tiers added later), using the hook's `SPLITS` immutable directly.
+- In `beforePayRecordedWith`, `calculateSplitAmounts` decodes tier IDs from payer metadata, computes `mulDiv(price, splitPercent, SPLITS_TOTAL_PERCENT)` per tier, and returns the total to be forwarded to the hook. The weight is adjusted down proportionally unless the `issueTokensForSplits` flag is set, in which case the full `context.weight` is returned.
 - In `afterPayRecordedWith`, `distributeAll` distributes forwarded funds to each tier's split group recipients. Leftover after all splits goes back to the project's balance via `addToBalance`.
 - Split recipients can be projects (via `terminal.pay` or `terminal.addToBalance`) or plain addresses (direct ETH transfer or `SafeERC20.safeTransfer`). Splits with no `projectId` and no `beneficiary` are skipped -- their share stays in the leftover and is routed to the project's own balance via `addToBalanceOf`, preventing a misconfigured split from bricking the payout distribution.
 
 ## Gotchas
 
-- `JB721TiersHook` is deployed as a **minimal clone** (not a full deployment). The constructor sets immutables (`RULESETS`, `STORE`, `DIRECTORY`, `METADATA_ID_TARGET`), and `initialize()` sets per-instance state. Calling `initialize()` twice reverts with `JB721TiersHook_AlreadyInitialized`.
+- `JB721TiersHook` is deployed as a **minimal clone** (not a full deployment). The constructor sets immutables (`RULESETS`, `STORE`, `SPLITS`, `DIRECTORY`, `METADATA_ID_TARGET`), and `initialize()` sets per-instance state. Calling `initialize()` twice reverts with `JB721TiersHook_AlreadyInitialized`.
 - **`JB721Hook` abstract base**: `JB721TiersHook` extends `JB721Hook`, which handles generic 721 hook lifecycle (terminal validation, burn loop, metadata decoding). `JB721TiersHook` overrides `cashOutWeightOf`, `totalCashOutWeight`, `_didBurn`, `_processPayment`, and `beforePayRecordedWith`. Errors like `JB721Hook_InvalidPay` and `JB721Hook_InvalidCashOut` are defined on the abstract class, not `JB721TiersHook`.
 - **Pricing context is bit-packed** into a single `uint256`: currency (bits 0-31), decimals (bits 32-39), prices contract address (bits 40-199). Read it via `pricingContext()`.
 - **Pricing decimals must be <= 18**: `initialize` reverts with `JB721TiersHook_InvalidPricingDecimals` otherwise.
@@ -169,6 +169,8 @@ Each tier has configurable voting power:
 - **Max initial supply per tier is 999,999,999** (`_ONE_BILLION - 1`). Exceeding this would cause token ID overflow into the next tier's ID space.
 - **`noNewTiersWithVotes` blocks all voting power**: It rejects tiers where voting units would be non-zero, whether from custom `votingUnits` or from a non-zero `price` (when `useVotingUnits` is false).
 - **`firstOwnerOf` is lazy**: The first owner is only stored when the token is first transferred away from its original holder. Before any transfer, `firstOwnerOf` returns the current owner.
+- **Tiers must be sorted by category, NOT price.** `recordAddTiers` reverts with `JB721TiersHookStore_InvalidCategorySortOrder` if tiers aren't in ascending category order. The `JB721InitTiersConfig` struct comment previously said "sorted by price" but the code enforces category ordering. Within the same category, tiers can be in any order.
+- **Always use `JB721TiersHookProjectDeployer.launchProjectFor` even without NFTs.** Pass an empty tiers array to enable future NFT additions without migration. If a project is launched via `JBController.launchProjectFor` instead, adding NFT tiers later requires wiring a new data hook into a new ruleset — using the 721 deployer from the start avoids this.
 
 ## Example Integration
 
@@ -223,7 +225,8 @@ tiers[0] = JB721TierConfig({
             noNewTiersWithReserves: false,
             noNewTiersWithVotes: false,
             noNewTiersWithOwnerMinting: false,
-            preventOverspending: false
+            preventOverspending: false,
+            issueTokensForSplits: false
         })
     }),
     launchProjectConfig: launchConfig,  // JBLaunchProjectConfig with rulesets, terminals, etc.

package/STYLE_GUIDE.md

@@ -0,0 +1,470 @@
+# Style Guide
+
+How we write Solidity and organize repos across the Juicebox V6 ecosystem. `nana-core-v6` is the gold standard — when in doubt, match what it does.
+
+## File Organization
+
+```
+src/
+├── Contract.sol              # Main contracts in root
+├── abstract/                 # Base contracts (JBPermissioned, JBControlled)
+├── enums/                    # One enum per file
+├── interfaces/               # One interface per file, prefixed with I
+├── libraries/                # Pure/view logic, prefixed with JB
+├── periphery/                # Utility contracts (deadlines, price feeds)
+└── structs/                  # One struct per file, prefixed with JB
+```
+
+One contract/interface/struct/enum per file. Name the file after the type it contains.
+
+**Structs, enums, libraries, and interfaces always go in their subdirectories** (`src/structs/`, `src/enums/`, `src/libraries/`, `src/interfaces/`) — never inline in contract files or placed in `src/` root. This keeps type definitions discoverable and import paths consistent across repos.
+
+## Pragma Versions
+
+```solidity
+// Contracts — pin to exact version
+pragma solidity 0.8.26;
+
+// Interfaces, structs, enums — caret for forward compatibility
+pragma solidity ^0.8.0;
+
+// Libraries — caret, may use newer features
+pragma solidity ^0.8.17;
+```
+
+## Imports
+
+Named imports only. Grouped by source, alphabetized within each group:
+
+```solidity
+// External packages (alphabetized)
+import {ERC2771Context} from "@openzeppelin/contracts/metatx/ERC2771Context.sol";
+import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
+import {SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
+import {mulDiv} from "@prb/math/src/Common.sol";
+
+// Local: abstract contracts
+import {JBPermissioned} from "./abstract/JBPermissioned.sol";
+
+// Local: interfaces (alphabetized)
+import {IJBController} from "./interfaces/IJBController.sol";
+import {IJBDirectory} from "./interfaces/IJBDirectory.sol";
+import {IJBMultiTerminal} from "./interfaces/IJBMultiTerminal.sol";
+
+// Local: libraries (alphabetized)
+import {JBConstants} from "./libraries/JBConstants.sol";
+import {JBFees} from "./libraries/JBFees.sol";
+
+// Local: structs (alphabetized)
+import {JBAccountingContext} from "./structs/JBAccountingContext.sol";
+import {JBSplit} from "./structs/JBSplit.sol";
+```
+
+## Contract Structure
+
+Section banners divide the contract into a fixed ordering. Every contract with 50+ lines uses these banners:
+
+```solidity
+/// @notice One-line description.
+contract JBExample is JBPermissioned, IJBExample {
+    // A library that does X.
+    using SomeLib for SomeType;
+
+    //*********************************************************************//
+    // --------------------------- custom errors ------------------------- //
+    //*********************************************************************//
+
+    error JBExample_SomethingFailed(uint256 amount);
+
+    //*********************************************************************//
+    // ------------------------- public constants ------------------------ //
+    //*********************************************************************//
+
+    uint256 public constant override FEE = 25;
+
+    //*********************************************************************//
+    // ----------------------- internal constants ------------------------ //
+    //*********************************************************************//
+
+    uint256 internal constant _FEE_BENEFICIARY_PROJECT_ID = 1;
+
+    //*********************************************************************//
+    // --------------- public immutable stored properties ---------------- //
+    //*********************************************************************//
+
+    IJBDirectory public immutable override DIRECTORY;
+
+    //*********************************************************************//
+    // --------------------- public stored properties -------------------- //
+    //*********************************************************************//
+
+    //*********************************************************************//
+    // -------------------- internal stored properties ------------------- //
+    //*********************************************************************//
+
+    //*********************************************************************//
+    // -------------------------- constructor ---------------------------- //
+    //*********************************************************************//
+
+    //*********************************************************************//
+    // ---------------------- receive / fallback ------------------------- //
+    //*********************************************************************//
+
+    //*********************************************************************//
+    // --------------------------- modifiers ----------------------------- //
+    //*********************************************************************//
+
+    //*********************************************************************//
+    // ---------------------- external transactions ---------------------- //
+    //*********************************************************************//
+
+    //*********************************************************************//
+    // ----------------------- external views ---------------------------- //
+    //*********************************************************************//
+
+    //*********************************************************************//
+    // ----------------------- public transactions ----------------------- //
+    //*********************************************************************//
+
+    //*********************************************************************//
+    // ----------------------- internal helpers -------------------------- //
+    //*********************************************************************//
+
+    //*********************************************************************//
+    // ----------------------- internal views ---------------------------- //
+    //*********************************************************************//
+
+    //*********************************************************************//
+    // ----------------------- private helpers --------------------------- //
+    //*********************************************************************//
+}
+```
+
+**Section order:**
+1. `using` declarations
+2. Custom errors
+3. Public constants
+4. Internal constants
+5. Public immutable stored properties
+6. Internal immutable stored properties
+7. Public stored properties
+8. Internal stored properties
+9. Constructor
+10. `receive` / `fallback`
+11. Modifiers
+12. External transactions
+13. External views
+14. Public transactions
+15. Internal helpers
+16. Internal views
+17. Private helpers
+
+Functions are alphabetized within each section.
+
+**Events:** Events are declared in interfaces only, never in implementation contracts. Implementations inherit events from their interface and emit them unqualified. This keeps the ABI definition in one place and allows tests to use interface-qualified event expectations (e.g., `emit IJBController.LaunchProject(...)`).
+
+## Interface Structure
+
+```solidity
+/// @notice One-line description.
+interface IJBExample is IJBBase {
+    // Events (with full NatSpec)
+
+    /// @notice Emitted when X happens.
+    /// @param projectId The ID of the project.
+    /// @param amount The amount transferred.
+    event SomethingHappened(uint256 indexed projectId, uint256 amount);
+
+    // Views (alphabetized)
+
+    /// @notice The directory of terminals and controllers.
+    function DIRECTORY() external view returns (IJBDirectory);
+
+    // State-changing functions (alphabetized)
+
+    /// @notice Does the thing.
+    /// @param projectId The ID of the project.
+    /// @return result The result.
+    function doThing(uint256 projectId) external returns (uint256 result);
+}
+```
+
+**Rules:**
+- Events first, then views, then state-changing functions
+- No custom errors in interfaces — errors belong in the implementing contract
+- Full NatSpec on every event, function, and parameter
+- Alphabetized within each group
+
+## Naming
+
+| Thing | Convention | Example |
+|-------|-----------|---------|
+| Contract | PascalCase | `JBMultiTerminal` |
+| Interface | `I` + PascalCase | `IJBMultiTerminal` |
+| Library | PascalCase | `JBCashOuts` |
+| Struct | PascalCase | `JBRulesetConfig` |
+| Enum | PascalCase | `JBApprovalStatus` |
+| Enum value | PascalCase | `ApprovalExpected` |
+| Error | `ContractName_ErrorName` | `JBMultiTerminal_FeeTerminalNotFound` |
+| Public constant | `ALL_CAPS` | `FEE`, `MAX_FEE` |
+| Internal constant | `_ALL_CAPS` | `_FEE_HOLDING_SECONDS` |
+| Public immutable | `ALL_CAPS` | `DIRECTORY`, `PERMISSIONS` |
+| Public/external function | `camelCase` | `cashOutTokensOf` |
+| Internal/private function | `_camelCase` | `_processFee` |
+| Internal storage | `_camelCase` | `_accountingContextForTokenOf` |
+| Function parameter | `camelCase` | `projectId`, `cashOutCount` |
+
+## NatSpec
+
+**Contracts:**
+```solidity
+/// @notice One-line description of what the contract does.
+contract JBExample is IJBExample {
+```
+
+**Functions:**
+```solidity
+/// @notice Records funds being added to a project's balance.
+/// @param projectId The ID of the project which funds are being added to.
+/// @param token The token being added.
+/// @param amount The amount added, as a fixed point number with the same decimals as the terminal.
+/// @return surplus The new surplus after adding.
+function recordAddedBalanceFor(
+    uint256 projectId,
+    address token,
+    uint256 amount
+) external override returns (uint256 surplus) {
+```
+
+**Structs:**
+```solidity
+/// @custom:member duration The number of seconds the ruleset lasts for. 0 means it never expires.
+/// @custom:member weight How many tokens to mint per unit paid (18 decimals).
+/// @custom:member weightCutPercent How much weight decays each cycle (9 decimals).
+struct JBRulesetConfig {
+    uint32 duration;
+    uint112 weight;
+    uint32 weightCutPercent;
+}
+```
+
+**Mappings:**
+```solidity
+/// @notice Context describing how a token is accounted for by a project.
+/// @custom:param projectId The ID of the project.
+/// @custom:param token The address of the token.
+mapping(uint256 projectId => mapping(address token => JBAccountingContext)) internal _accountingContextForTokenOf;
+```
+
+## Numbers
+
+Use underscores for thousands separators:
+
+```solidity
+uint256 internal constant _FEE_HOLDING_SECONDS = 2_419_200; // 28 days
+uint32 public constant MAX_WEIGHT_CUT_PERCENT = 1_000_000_000;
+uint256 public constant MAX_RESERVED_PERCENT = 10_000;
+```
+
+## Function Calls
+
+Use named parameters for readability when calling functions with 3+ arguments:
+
+```solidity
+PERMISSIONS.hasPermission({
+    operator: sender,
+    account: account,
+    projectId: projectId,
+    permissionId: permissionId,
+    includeRoot: true,
+    includeWildcardProjectId: true
+});
+```
+
+## Multiline Signatures
+
+```solidity
+function recordCashOutFor(
+    address holder,
+    uint256 projectId,
+    uint256 cashOutCount,
+    JBAccountingContext calldata accountingContext
+)
+    external
+    override
+    returns (
+        JBRuleset memory ruleset,
+        uint256 reclaimAmount,
+        JBCashOutHookSpecification[] memory hookSpecifications
+    )
+{
+```
+
+Modifiers and return types go on their own indented lines.
+
+## Error Handling
+
+- Validate inputs with explicit `revert` + custom error
+- Use `try-catch` only for external calls to untrusted contracts (hooks, fee processing)
+- Always include relevant context in error parameters
+
+```solidity
+// Direct validation
+if (amount > limit) revert JBTerminalStore_InadequateControllerPayoutLimit(amount, limit);
+
+// External call to untrusted hook
+try hook.afterPayRecordedWith(context) {} catch (bytes memory reason) {
+    emit HookAfterPayReverted(hook, context, reason, _msgSender());
+}
+```
+
+---
+
+## DevOps
+
+### foundry.toml
+
+Standard config across all repos:
+
+```toml
+[profile.default]
+solc = '0.8.26'
+evm_version = 'cancun'
+optimizer_runs = 200
+libs = ["node_modules", "lib"]
+fs_permissions = [{ access = "read-write", path = "./"}]
+
+[profile.ci_sizes]
+optimizer_runs = 200
+
+[fuzz]
+runs = 4096
+
+[invariant]
+runs = 1024
+depth = 100
+fail_on_revert = false
+
+[fmt]
+number_underscore = "thousands"
+multiline_func_header = "all"
+wrap_comments = true
+```
+
+**Variations:**
+- `evm_version = 'cancun'` for repos using transient storage (buyback-hook, router-terminal, univ4-router)
+- `via_ir = true` for repos hitting stack-too-deep (buyback-hook, banny-retail, univ4-lp-split-hook, deploy-all)
+- `optimizer = false` only for deploy-all-v6 (stack-too-deep with optimization)
+
+This repo uses the standard config with no deviations: `cancun`, `optimizer_runs=200`, no `via_ir`.
+
+### CI Workflows
+
+Every repo has at minimum `test.yml` and `lint.yml`:
+
+**test.yml:**
+```yaml
+name: test
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+jobs:
+  forge-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22.4.x
+      - name: Install npm dependencies
+        run: npm install --omit=dev
+      - name: Install Foundry
+        uses: foundry-rs/foundry-toolchain@v1
+      - name: Run tests
+        run: forge test --fail-fast --summary --detailed --skip "*/script/**"
+      - name: Check contract sizes
+        run: FOUNDRY_PROFILE=ci_sizes forge build --sizes --skip "*/test/**" --skip "*/script/**" --skip SphinxUtils
+```
+
+**lint.yml:**
+```yaml
+name: lint
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+jobs:
+  forge-fmt:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install Foundry
+        uses: foundry-rs/foundry-toolchain@v1
+      - name: Check formatting
+        run: forge fmt --check
+```
+
+### package.json
+
+```json
+{
+  "name": "@bananapus/721-hook-v6",
+  "version": "x.x.x",
+  "license": "MIT",
+  "repository": { "type": "git", "url": "git+https://github.com/Org/repo.git" },
+  "engines": { "node": ">=20.0.0" },
+  "scripts": {
+    "test": "forge test",
+    "coverage": "forge coverage --match-path \"./src/*.sol\" --report lcov --report summary"
+  },
+  "dependencies": { ... },
+  "devDependencies": {
+    "@sphinx-labs/plugins": "^0.33.2"
+  }
+}
+```
+
+**Scoping:** `@bananapus/` for Bananapus repos, `@rev-net/` for revnet, `@croptop/` for croptop, `@bannynet/` for banny, `@ballkidz/` for defifa.
+
+### remappings.txt
+
+Every repo has a `remappings.txt`. Minimal content:
+
+```
+@sphinx-labs/contracts/=lib/sphinx/packages/contracts/contracts/foundry
+```
+
+Additional mappings as needed for repo-specific dependencies.
+
+### Formatting
+
+Run `forge fmt` before committing. The `[fmt]` config in `foundry.toml` enforces:
+- Thousands separators on numbers (`1_000_000`)
+- Multiline function headers when multiple parameters
+- Wrapped comments at reasonable width
+
+CI checks formatting via `forge fmt --check`.
+
+### Branching
+
+- `main` is the primary branch
+- Feature branches for PRs
+- All PRs trigger test + lint workflows
+- Submodule checkout with `--recursive` in CI
+
+### Dependencies
+
+- Solidity dependencies via npm (`node_modules/`)
+- `forge-std` as a git submodule in `lib/`
+- Sphinx plugins as a devDependency
+- Cross-repo references use `file:../sibling-repo` in local development
+- Published versions use semver ranges (`^0.0.x`) for npm
+
+### Contract Size Checks
+
+CI runs `FOUNDRY_PROFILE=ci_sizes forge build --sizes` to catch contracts approaching the 24KB limit. The `ci_sizes` profile uses `optimizer_runs = 200` for realistic size measurement even when the default profile has different optimizer settings.

package/docs/src/src/JB721TiersHookStore.sol/contract.JB721TiersHookStore.md

@@ -167,7 +167,7 @@ mapping(address hook => mapping(uint256 tierId => JBStored721Tier)) internal _st
 
 
 ### _tierIdAfter
-Returns the ID of the tier which comes after the provided tier ID (sorted by price).
+Returns the ID of the tier which comes after the provided tier ID (sorted by category).
 
 *If empty, assume the next tier ID should come after.*
 
@@ -386,7 +386,7 @@ function tiersOf(
 |`hook`|`address`|The 721 contract to get the tiers of.|
 |`categories`|`uint256[]`|An array tier categories to get tiers from. Send an empty array to get all categories.|
 |`includeResolvedUri`|`bool`|If set to `true`, if the contract has a token URI resolver, its content will be resolved and included.|
-|`startingId`|`uint256`|The ID of the first tier to get (sorted by price). Send 0 to get all active tiers.|
+|`startingId`|`uint256`|The ID of the first tier to get (sorted by category). Send 0 to get all active tiers.|
 |`size`|`uint256`|The number of tiers to include.|
 
 **Returns**
@@ -561,7 +561,7 @@ function totalCashOutWeight(address hook) public view override returns (uint256
 
 ### _firstSortedTierIdOf
 
-Get the first tier ID from an 721 contract (when sorted by price) within a provided category.
+Get the first tier ID from an 721 contract (when sorted by category) within a provided category.
 
 
 ```solidity
@@ -669,7 +669,7 @@ function _isTierRemovedWithRefresh(
 
 ### _lastSortedTierIdOf
 
-The last sorted tier ID from an 721 contract (when sorted by price).
+The last sorted tier ID from an 721 contract (when sorted by category).
 
 
 ```solidity
@@ -690,7 +690,7 @@ function _lastSortedTierIdOf(address hook) internal view returns (uint256 id);
 
 ### _nextSortedTierIdOf
 
-Get the tier ID which comes after the provided one when sorted by price.
+Get the tier ID which comes after the provided one when sorted by category.
 
 
 ```solidity

package/docs/src/src/structs/JB721InitTiersConfig.sol/struct.JB721InitTiersConfig.md

@@ -3,7 +3,7 @@
 
 Config to initialize a `JB721TiersHook` with tiers and price data.
 
-*The `tiers` must be sorted by price (from least to greatest).*
+*The `tiers` must be sorted by category (from least to greatest).*
 
 **Notes:**
 - member: tiers The tiers to initialize the hook with.

package/foundry.toml

@@ -1,6 +1,6 @@
 [profile.default]
 solc = '0.8.26'
-evm_version = 'paris'
+evm_version = 'cancun'
 optimizer_runs = 200
 libs = ["node_modules", "lib"]
 fs_permissions = [{ access = "read-write", path = "./"}]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/721-hook-v6",
-  "version": "0.0.10",
+  "version": "0.0.12",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -17,10 +17,10 @@
     "artifacts": "source ./.env && npx sphinx artifacts --org-id 'ea165b21-7cdc-4d7b-be59-ecdd4c26bee4' --project-name 'nana-721-hook-v6'"
   },
   "dependencies": {
-    "@bananapus/address-registry-v6": "^0.0.4",
-    "@bananapus/core-v6": "^0.0.10",
-    "@bananapus/ownable-v6": "^0.0.6",
-    "@bananapus/permission-ids-v6": "^0.0.5",
+    "@bananapus/address-registry-v6": "^0.0.6",
+    "@bananapus/core-v6": "^0.0.12",
+    "@bananapus/ownable-v6": "^0.0.7",
+    "@bananapus/permission-ids-v6": "^0.0.6",
     "@openzeppelin/contracts": "5.2.0",
     "@prb/math": "^4.1.0",
     "solady": "^0.1.8"

package/script/Deploy.s.sol

@@ -74,13 +74,13 @@ contract DeployScript is Script, Sphinx {
             (address _hook, bool _hookIsDeployed) = _isDeployed(
                 HOOK_SALT,
                 type(JB721TiersHook).creationCode,
-                abi.encode(core.directory, core.permissions, core.rulesets, store, TRUSTED_FORWARDER)
+                abi.encode(core.directory, core.permissions, core.rulesets, store, core.splits, TRUSTED_FORWARDER)
             );
 
             // Deploy it if it has not been deployed yet.
             hook = !_hookIsDeployed
                 ? new JB721TiersHook{salt: HOOK_SALT}(
-                    core.directory, core.permissions, core.rulesets, store, TRUSTED_FORWARDER
+                    core.directory, core.permissions, core.rulesets, store, core.splits, TRUSTED_FORWARDER
                 )
                 : JB721TiersHook(_hook);
         }