@bananapus/univ4-lp-split-hook-v6 0.0.5 → 0.0.6

package/.github/workflows/lint.yml

@@ -1,21 +1,15 @@
 name: lint
 on:
   pull_request:
-    branches:
-      - main
+    branches: [main]
   push:
-    branches:
-      - main
+    branches: [main]
 jobs:
-  forge-lint:
+  forge-fmt:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-        with:
-          submodules: recursive
       - name: Install Foundry
         uses: foundry-rs/foundry-toolchain@v1
-      - name: Install npm dependencies
-        run: npm ci
-      - name: Check linting
+      - name: Check formatting
         run: forge fmt --check

package/.github/workflows/slither.yml

@@ -1,24 +1,23 @@
 name: slither
 on:
-    pull_request:
-      branches:
-        - main
-    push:
-      branches:
-        - main
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
 jobs:
-  analyze:
+  slither:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
         with:
           submodules: recursive
-      - name: Install Foundry
-        uses: foundry-rs/foundry-toolchain@v1
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22.4.x
       - name: Install npm dependencies
-        run: npm ci
-      - name: Run slither
+        run: npm install --omit=dev
+      - name: Run Slither
         uses: crytic/slither-action@v0.3.1
         with:
-            slither-config: slither-ci.config.json
-            fail-on: medium
+          slither-config: slither-ci.config.json
+          fail-on: medium

package/.github/workflows/test.yml

@@ -1,13 +1,11 @@
 name: test
 on:
-  push:
+  pull_request:
     branches:
       - main
-  pull_request:
+  push:
     branches:
       - main
-  workflow_dispatch:
-
 jobs:
   forge-test:
     runs-on: ubuntu-latest
@@ -15,11 +13,14 @@ jobs:
       - 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: Install npm dependencies
-        run: npm ci
       - name: Run tests
-        run: forge test --fail-fast
+        run: forge test --fail-fast --summary --detailed --skip "*/script/**"
       - name: Check contract sizes
-        run: forge build --sizes --skip "*/test/**" --skip "*/script/**"
+        run: FOUNDRY_PROFILE=ci_sizes forge build --sizes --skip "*/test/**" --skip "*/script/**" --skip SphinxUtils

package/ADMINISTRATION.md

@@ -0,0 +1,109 @@
+# Administration
+
+Admin privileges and their scope in univ4-lp-split-hook-v6.
+
+## Roles
+
+### 1. Project Owner
+
+- **Assigned by:** Owning the JBProjects ERC-721 NFT for the given `projectId`.
+- **Scope:** Per-project. Each project has its own owner, and ownership is verified through `IJBDirectory(DIRECTORY).PROJECTS().ownerOf(projectId)`.
+- **Used for:** Gating `deployPool`, `rebalanceLiquidity`, and `claimFeeTokensFor`.
+
+### 2. Authorized Operator (SET_BUYBACK_POOL)
+
+- **Assigned by:** Project owner granting `JBPermissionIds.SET_BUYBACK_POOL` (permission ID 23) via `JBPermissions.setPermission(operator, account, projectId, permissionId, true)`.
+- **Scope:** Per-project, per-operator. The operator can act on behalf of the project owner for functions that require `SET_BUYBACK_POOL`.
+- **Used for:** Same functions as the project owner -- `deployPool`, `rebalanceLiquidity`, and `claimFeeTokensFor`.
+
+### 3. Hook Deployer (Anyone)
+
+- **Assigned by:** No assignment required. Anyone can call `UniV4DeploymentSplitHookDeployer.deployHookFor()`.
+- **Scope:** Global. The caller becomes the initial context for the deployed clone (their address is included in the CREATE2 salt scoping).
+
+### 4. JB Controller (System Role)
+
+- **Assigned by:** The Juicebox directory's `controllerOf(projectId)` mapping. Not directly assignable by the hook.
+- **Scope:** Per-project. Only the controller registered for a given project can call `processSplitWith`.
+- **Used for:** Sending reserved tokens to the hook during distribution.
+
+## Privileged Functions
+
+### UniV4DeploymentSplitHook
+
+| Function | Required Role | Permission ID | Scope | What It Does |
+|----------|--------------|---------------|-------|-------------|
+| `deployPool(projectId, terminalToken, amount0Min, amount1Min, minCashOutReturn)` | Project owner or SET_BUYBACK_POOL operator. **Becomes permissionless** when the current ruleset weight has decayed to 1/10th or less of `initialWeightOf[projectId]`. | `JBPermissionIds.SET_BUYBACK_POOL` (23) | Per-project, per-terminal-token | Creates a Uniswap V4 pool at the geometric mean of issuance/cashout rates. Cashes out a computed fraction of accumulated project tokens for terminal tokens, mints a concentrated LP position, and transitions the project from accumulation to burn mode. (Lines 491-531) |
+| `rebalanceLiquidity(projectId, terminalToken, ...)` | Project owner or SET_BUYBACK_POOL operator | `JBPermissionIds.SET_BUYBACK_POOL` (23) | Per-project, per-terminal-token | Burns the existing LP position NFT, collects and routes accrued fees, recalculates tick bounds from current issuance/cashout rates, and mints a new position with updated bounds. Reverts with `InsufficientLiquidity` if the new position would have zero liquidity. (Lines 559-658) |
+| `claimFeeTokensFor(projectId, beneficiary)` | Project owner or SET_BUYBACK_POOL operator | `JBPermissionIds.SET_BUYBACK_POOL` (23) | Per-project | Transfers accumulated fee-project tokens to the specified beneficiary address. Validates the caller's permission, not the beneficiary's identity. Zeroes `claimableFeeTokens[projectId]` before transferring. (Lines 441-456) |
+| `processSplitWith(context)` | JB Controller (system) | None (checked via `controllerOf`) | Per-project | Only callable by the project's registered controller. Accumulates project tokens (pre-deployment) or burns them (post-deployment). Validates `context.split.hook == address(this)`, `groupId == 1`, and controller identity. (Lines 534-555) |
+| `initialize(feeProjectId, feePercent)` | Anyone (once only) | None | Per-clone instance | Sets `FEE_PROJECT_ID` and `FEE_PERCENT` on a clone. Can only be called once per clone (`initialized` flag). In practice, called immediately by the deployer factory. (Lines 177-194) |
+
+### UniV4DeploymentSplitHookDeployer
+
+| Function | Required Role | Permission ID | Scope | What It Does |
+|----------|--------------|---------------|-------|-------------|
+| `deployHookFor(feeProjectId, feePercent, salt)` | Anyone | None | Global | Deploys a new hook clone via `LibClone`, calls `initialize()` on it, and registers it in the `JBAddressRegistry`. CREATE2 salt is scoped to `msg.sender`. (Lines 52-84) |
+
+### Permissionless Functions (No Privilege Required)
+
+| Function | Scope | What It Does |
+|----------|-------|-------------|
+| `collectAndRouteLPFees(projectId, terminalToken)` | Per-project, per-terminal-token | Collects accrued V4 position fees and routes them: `FEE_PERCENT` of terminal token fees to the fee project via `terminal.pay()`, the remainder to the original project via `addToBalanceOf()`. Project token fees are burned. Safe because funds always go to verified project terminals. (Lines 459-488) |
+| `isPoolDeployed(projectId, terminalToken)` | View | Returns whether `tokenIdOf[projectId][terminalToken] != 0`. |
+| `poolKeyOf(projectId, terminalToken)` | View | Returns the stored `PoolKey` for a deployed pool. |
+| `supportsInterface(interfaceId)` | View | Returns `true` for `IUniV4DeploymentSplitHook` and `IJBSplitHook`. |
+| `receive()` | Accepts ETH | Required for cash-out with native ETH and V4 TAKE operations. |
+
+## Immutable Configuration
+
+These values are set at deploy time and cannot be changed afterward.
+
+### Implementation-Level (Constructor, Shared Across All Clones)
+
+| Parameter | Set In | Value Source |
+|-----------|--------|-------------|
+| `DIRECTORY` | Constructor (line 168) | JBDirectory address |
+| `TOKENS` | Constructor (line 169) | JBTokens address |
+| `POOL_MANAGER` | Constructor (line 170) | Uniswap V4 PoolManager address |
+| `POSITION_MANAGER` | Constructor (line 171) | Uniswap V4 PositionManager address |
+| `PERMISSIONS` | Inherited from `JBPermissioned` constructor (line 161) | JBPermissions address |
+
+### Clone-Level (initialize(), Per-Instance)
+
+| Parameter | Set In | Value Source |
+|-----------|--------|-------------|
+| `FEE_PROJECT_ID` | `initialize()` (line 192) | Project ID receiving LP fee share |
+| `FEE_PERCENT` | `initialize()` (line 193) | Basis points (0-10000) of LP fees routed to fee project |
+
+### Protocol Constants (Hardcoded)
+
+| Constant | Value | Purpose |
+|----------|-------|---------|
+| `BPS` | 10,000 | 100% in basis points |
+| `POOL_FEE` | 10,000 | 1% Uniswap V4 fee tier |
+| `TICK_SPACING` | 200 | Tick spacing for the 1% fee tier |
+
+## Admin Boundaries
+
+What admins **cannot** do:
+
+1. **Cannot change fee configuration after initialization.** `FEE_PROJECT_ID` and `FEE_PERCENT` are write-once via `initialize()`. The `initialized` flag prevents re-initialization, even by the original deployer.
+
+2. **Cannot withdraw accumulated tokens directly.** There is no `withdraw()` or `rescue()` function. Accumulated project tokens can only exit via `deployPool()` (into LP) or post-deployment burning.
+
+3. **Cannot redirect LP fees to arbitrary addresses.** Fee routing is hardcoded to go through `primaryTerminalOf` for both the fee project and the original project. There is no admin-settable destination.
+
+4. **Cannot modify pool parameters after deployment.** The `PoolKey` (fee tier, tick spacing, hook address, currency pair) is set during `_createAndInitializePool()` and stored immutably in `_poolKeys`.
+
+5. **Cannot deploy a second pool for the same project/terminal-token pair.** `deployPool()` reverts with `PoolAlreadyDeployed` if `tokenIdOf[projectId][terminalToken] != 0`.
+
+6. **Cannot prevent permissionless fee collection.** `collectAndRouteLPFees()` has no access control. Anyone can trigger fee collection and routing for any deployed pool.
+
+7. **Cannot prevent permissionless pool deployment after 10x weight decay.** Once the current ruleset weight drops to 1/10th of `initialWeightOf[projectId]`, the `SET_BUYBACK_POOL` permission check is bypassed and anyone can deploy.
+
+8. **Cannot change the Uniswap V4 infrastructure contracts.** `POOL_MANAGER`, `POSITION_MANAGER`, `DIRECTORY`, `TOKENS`, and `PERMISSIONS` are immutable, set in the implementation constructor, and shared across all clones.
+
+9. **Cannot control which project tokens are sent via `processSplitWith`.** The controller decides when and how much to distribute. The hook only receives what the JB protocol sends it.
+
+10. **Cannot recover funds sent to the wrong clone.** If tokens are sent directly (not through `processSplitWith`), there is no mechanism to retrieve them. Only project tokens sent via the controller accumulate correctly.

package/ARCHITECTURE.md

@@ -0,0 +1,58 @@
+# univ4-lp-split-hook-v6 — Architecture
+
+## Purpose
+
+Uniswap V4 liquidity pool deployment hook for Juicebox V6. Receives project tokens via reserved token splits, accumulates them until a deployment threshold is met, then creates a Uniswap V4 pool and provides initial liquidity. After deployment, burns new tokens and routes LP fees back to the project.
+
+## Contract Map
+
+```
+src/
+├── UniV4DeploymentSplitHook.sol         — Split hook: token accumulation, pool deployment, LP management
+├── UniV4DeploymentSplitHookDeployer.sol — Factory for deploying split hooks
+└── interfaces/
+    └── IUniV4DeploymentSplitHook.sol
+```
+
+## Key Data Flows
+
+### Pre-Deployment (Accumulation)
+```
+Reserved token distribution → JBMultiTerminal.sendPayoutsOf()
+  → Split to UniV4DeploymentSplitHook.processSplitWith()
+    → Accumulate project tokens
+    → Track accumulated balance
+
+Owner/Operator → deployPool()
+  → Validate: enough tokens accumulated
+  → Create Uniswap V4 pool (projectToken/terminalToken)
+  → Provide initial liquidity from accumulated tokens
+  → Set up LP position
+```
+
+### Post-Deployment (Maintenance)
+```
+Reserved token distribution → processSplitWith()
+  → Burn newly received project tokens (no more accumulation)
+
+Anyone → rebalanceLiquidity()
+  → Adjust LP position based on current rates
+  → Route LP fees back to project
+```
+
+## Extension Points
+
+| Point | Interface | Purpose |
+|-------|-----------|---------|
+| Split hook | `IJBSplitHook` | Receives tokens from reserved distribution |
+| Pool deployment | Uniswap V4 PositionManager | Creates and manages LP positions |
+
+## Dependencies
+- `@bananapus/core-v6` — Core protocol
+- `@bananapus/permission-ids-v6` — SET_BUYBACK_POOL permission
+- `@bananapus/ownable-v6` — JB ownership
+- `@openzeppelin/contracts` — SafeERC20, Ownable
+- `@prb/math` — mulDiv, sqrt
+- `@uniswap/v4-core` — Pool manager, currency types
+- `@uniswap/v4-periphery` — Position manager, actions
+- `@rev-net/core-v6` — Revnet integration

package/README.md

@@ -26,7 +26,7 @@ This ensures the AMM price always trades within the project's intrinsic economic
 2. Controller distributes reserved tokens → processSplitWith()
    → Tokens accumulate in accumulatedProjectTokens[projectId]
    |
-3. Project owner calls deployPool(projectId, terminalToken, ...)
+3. Project owner (or anyone after 10x weight decay) calls deployPool(...)
    → Creates V4 pool at geometric mean of [cashOut, issuance] rates
    → Cashes out optimal fraction of tokens for terminal tokens
    → Mints concentrated LP position bounded by rate-derived ticks
@@ -96,7 +96,7 @@ forge install
 # foundry.toml
 [profile.default]
 solc = '0.8.26'
-evm_version = 'paris'
+evm_version = 'cancun'
 optimizer_runs = 200
 via_ir = true
 
@@ -122,7 +122,9 @@ test/
   NativeETHTest.t.sol                        # Native ETH handling
   PriceMathTest.t.sol                        # Price conversion math
   SecurityTest.t.sol                         # Permission checks, access control
+  WeightDecayDeployTest.t.sol               # Permissionless deploy after 10x weight decay
   IntegrationLifecycle.t.sol                 # Full end-to-end workflow
+  Fork.t.sol                                 # Fork tests with real V4 + JB core
   TestBaseV4.sol                             # Shared test infrastructure
   regression/                               # Audit finding regression tests (M-31, M-32, L-25)
 script/
@@ -133,11 +135,13 @@ script/
 
 | Permission | Required For |
 |------------|-------------|
-| `SET_BUYBACK_POOL` | `deployPool` -- create V4 pool and mint LP position |
+| `SET_BUYBACK_POOL` | `deployPool` -- create V4 pool and mint LP position (unless weight has decayed 10x) |
 | `SET_BUYBACK_POOL` | `claimFeeTokensFor` -- claim accumulated fee-project tokens |
 
 Note: `collectAndRouteLPFees` and `rebalanceLiquidity` are **permissionless** -- anyone can call them. This is safe because they only operate on existing positions and route funds to verified project terminals.
 
+`deployPool` also becomes **permissionless** when the current ruleset's weight has decayed to 1/10th or less of the weight when the hook first started accumulating tokens. This prevents a stale owner from blocking LP deployment indefinitely.
+
 ## Risks
 
 - **Impermanent loss:** The LP position is subject to standard concentrated liquidity IL. If the market price moves outside the [cashOut, issuance] range, the position becomes single-sided.

package/RISKS.md

@@ -0,0 +1,235 @@
+# univ4-lp-split-hook-v6 -- Risks
+
+Deep implementation-level risk analysis. Line references are to `src/UniV4DeploymentSplitHook.sol` unless otherwise noted.
+
+## Trust Assumptions
+
+1. **Project Owner** -- Can trigger pool deployment (`deployPool`, line 491) and manage LP positions (`rebalanceLiquidity`, line 559). Has `SET_BUYBACK_POOL` permission and can delegate it. Cannot modify fee configuration post-initialization.
+2. **Uniswap V4 Pool Manager + Position Manager** -- LP positions are managed through V4 PositionManager (immutable at line 107). Pool manager bugs or governance changes could affect all positions managed by this hook. The hook has no way to migrate positions to a different V4 deployment.
+3. **JB Core Protocol** -- The hook trusts that `controllerOf(projectId)` returns the legitimate controller (line 537-539), that `processSplitWith` is called with accurate `context.amount` (line 534), and that `primaryTerminalOf` resolves correctly (line 236, 346-347, 521-522). Compromise of the JB directory would break all assumptions.
+4. **Price Oracle (Implicit)** -- Initial pool price is derived from the project's bonding curve rates via `currentReclaimableSurplusOf` (line 238) and `currentRulesetOf` weight (line 290, 344, 401). These are on-chain reads, not external oracle feeds. Manipulation requires changing the project's actual surplus or ruleset weight.
+5. **Fee Project** -- The `FEE_PROJECT_ID` must have a functioning terminal that accepts the terminal token. If the fee project's terminal disappears or reverts, fee routing silently fails (the terminal check at line 1105 returns early, and the fee amount is retained in the contract).
+
+## Audit History
+
+A Nemesis audit (`.audit/findings/nemesis-verified.md`) identified 6 true positives. All findings have been addressed in the current codebase:
+
+| Finding | Severity | Status | Fix Applied |
+|---------|----------|--------|-------------|
+| NM-001: Permissionless rebalance bricks LP | HIGH | **Fixed** | Added `SET_BUYBACK_POOL` permission check to `rebalanceLiquidity` (line 569-573). Added `InsufficientLiquidity` revert guard when new position would have zero liquidity (line 646-652). |
+| NM-002: Placeholder disables fee routing in rebalance | MEDIUM | **Fixed** | Replaced `_getAmountForCurrency()` with balance-delta tracking in `rebalanceLiquidity` (lines 587-602), matching the pattern used in `collectAndRouteLPFees`. |
+| NM-003: Per-project flag prevents multi-terminal-token pools | MEDIUM | **Fixed** | Changed `projectDeployed` to `mapping(uint256 => mapping(address => bool))` (line 129). Added `deployedPoolCount` (line 134) for the accumulate-vs-burn decision in `processSplitWith` (line 545). |
+| NM-004: Implementation contract initializable by anyone | LOW | **Acknowledged** | The implementation is not intended for direct use. Clones have separate storage. Low practical impact. |
+| NM-005: Dead variables in rebalanceLiquidity | LOW | **Fixed** | Dead variables removed; balance-delta tracking replaces them. |
+| NM-006: _poolKeys not cleared when tokenIdOf zeroed | LOW | **Mitigated** | `rebalanceLiquidity` now reverts instead of zeroing `tokenIdOf` (line 652), making the stale-data path unreachable. |
+
+## Known Risks
+
+### Severity: HIGH
+
+#### H-1. Rebalance Sandwich Attack (MEV)
+
+- **Severity:** HIGH
+- **Tested:** Partially. `RebalanceTest.t.sol` tests the function mechanics and authorization but does not simulate MEV sandwich attacks.
+- **Lines:** 559-658 (rebalanceLiquidity), specifically 607-613 (BURN_POSITION + TAKE_PAIR)
+- **Description:** `rebalanceLiquidity` burns the entire LP position and mints a new one in a single transaction. Between the BURN_POSITION (which removes liquidity at the current pool price) and MINT_POSITION (which adds liquidity at new tick bounds), the hook holds both token types as raw balances. A sophisticated MEV bot can sandwich this transaction:
+  1. Front-run: Swap in the V4 pool to move the price to one extreme of the tick range, making the BURN return skewed token amounts.
+  2. The rebalance executes, minting a new position at the manipulated price point.
+  3. Back-run: Swap back, extracting value from the new position's skewed liquidity.
+- **Slippage parameters** (`decreaseAmount0Min`, `decreaseAmount1Min`, `increaseAmount0Min`, `increaseAmount1Min`) provide some protection but require the caller to set them correctly. The default of `0` offers no protection.
+- **Mitigation:** Callers should use private mempools (e.g., Flashbots Protect) and set non-zero slippage parameters. The 1% fee tier (POOL_FEE = 10,000) increases the cost of sandwich attacks.
+
+#### H-2. collectAndRouteLPFees Sandwich Attack (MEV)
+
+- **Severity:** HIGH
+- **Tested:** `FeeRoutingTest.t.sol` tests fee arithmetic and routing but not MEV vectors.
+- **Lines:** 459-488 (collectAndRouteLPFees), specifically 471-477 (DECREASE_LIQUIDITY + TAKE_PAIR)
+- **Description:** `collectAndRouteLPFees` is permissionless (no access control). A MEV bot can:
+  1. Observe a pending `collectAndRouteLPFees` transaction.
+  2. Front-run: Swap in the pool to manipulate the price, affecting the value of collected fees.
+  3. The fee collection executes, routing fees at the manipulated value.
+  4. Back-run: Swap back.
+- **Impact is lower than H-1** because fee collection only touches accrued fees (not the full position principal), but large accumulated fees create meaningful MEV opportunities.
+- **Mitigation:** The 1% pool fee makes sandwich attacks costly relative to extracted value. Frequent fee collection reduces the size of any single extraction.
+
+### Severity: MEDIUM
+
+#### M-1. Impermanent Loss on Concentrated Liquidity
+
+- **Severity:** MEDIUM (inherent to AMM design)
+- **Tested:** Not directly tested. The tick bounds are tested in `PriceMathTest.t.sol` (test_TickBounds_Normal, test_TickBounds_AlignedToSpacing).
+- **Lines:** 798-820 (_calculateTickBounds), 862-922 (_computeOptimalCashOutAmount)
+- **Description:** The LP position is concentrated between the cashout rate (price floor, line 807) and issuance rate (price ceiling, line 808). If the market price moves outside this range, the position becomes 100% single-sided and stops earning fees. Concentrated liquidity amplifies impermanent loss compared to full-range V3/V2 positions. With a 1% fee tier and 200-tick spacing, the position range is relatively wide, limiting but not eliminating this risk.
+- **Mitigation:** `rebalanceLiquidity` allows repositioning to track changing rates. The tick range is derived from the project's actual issuance and cashout parameters, so it tracks fundamental value.
+
+#### M-2. Initial Pool Price Manipulation
+
+- **Severity:** MEDIUM
+- **Tested:** `PriceMathTest.t.sol` tests the geometric mean calculation (test_GeometricMean_BetweenBounds, test_GeometricMean_FallbackOnZeroCashOut). `WeightDecayDeployTest.t.sol` tests the weight-zero edge case.
+- **Lines:** 822-859 (_computeInitialSqrtPrice), 702-706 (cash-out amount computation)
+- **Description:** The initial pool price is the geometric mean of the cashout and issuance rates (line 851). These rates are derived from on-chain state (`currentReclaimableSurplusOf` at line 238, `currentRulesetOf` at line 290). If an attacker can manipulate the project's surplus (by paying in then cashing out) or trigger a ruleset change just before `deployPool`, the initial price will be skewed.
+- **Attack scenario:**
+  1. Attacker pays a large amount into the project, inflating surplus.
+  2. Owner calls `deployPool`, which computes the initial price from the inflated surplus.
+  3. Pool is created at an artificially high cashout rate.
+  4. Attacker cashes out, reducing surplus back to normal.
+  5. The pool's initial price is now misaligned, creating arbitrage profit for the attacker.
+- **Mitigation:** The bonding curve math in JB core limits the degree of price manipulation. The `minCashOutReturn` parameter (line 496) provides slippage protection on the cash-out portion. The 1% auto-tolerance (line 716-721) provides a default safety margin.
+
+#### M-3. Token Accumulation Period: No Yield, Counterparty Risk
+
+- **Severity:** MEDIUM
+- **Tested:** `AccumulationStageTest.t.sol` covers accumulation mechanics. `DeploymentStageTest.t.sol` tests the transition.
+- **Lines:** 665-667 (_accumulateTokens), 545-551 (processSplitWith accumulation branch)
+- **Description:** Between the first `processSplitWith` call and the eventual `deployPool`, project tokens sit in the contract earning no yield. During this period:
+  - The contract holds raw ERC-20 tokens with no protective mechanism.
+  - Token value may decrease as the project's issuance rate decays (the weight cut mechanism).
+  - If the project owner never calls `deployPool`, tokens are stranded until weight decays 10x (line 506) and becomes permissionless.
+- **Mitigation:** The 10x weight decay permissionless deployment (line 500-512, tested in `WeightDecayDeployTest.t.sol`) ensures pools can eventually be deployed even without owner cooperation. The `initialWeightOf` tracking (line 547-549) records the weight at first accumulation.
+
+#### M-4. Rebalance Reverts: Temporary Position Gap
+
+- **Severity:** MEDIUM
+- **Tested:** `M31_StaleTokenIdOf.t.sol` tests the `InsufficientLiquidity` revert. `UniV4DeploymentSplitHook_AuditFindings.t.sol` (test_H2_rebalance_zeroLiquidity_reverts) confirms the guard.
+- **Lines:** 605-614 (BURN_POSITION in rebalanceLiquidity), 638-653 (liquidity check and revert)
+- **Description:** `rebalanceLiquidity` burns the old position (line 607-613) before minting the new one (line 641-643). If the MINT_POSITION step fails (e.g., due to price moving outside tick bounds causing zero liquidity), the transaction reverts with `InsufficientLiquidity` (line 652), rolling back the burn. This is the correct behavior (prevents bricking), but it means the rebalance cannot succeed until conditions change. During the revert, no state changes occur, and the old position remains intact.
+- **Edge case:** If the V4 PositionManager itself has a bug or is paused, neither burn nor mint would succeed, effectively freezing the position in place.
+
+#### M-5. Fee Project Terminal Disappearance
+
+- **Severity:** MEDIUM
+- **Tested:** `L25_FeeProjectIdValidation.t.sol` tests the `initialize` validation. Fee routing is tested in `FeeRoutingTest.t.sol`.
+- **Lines:** 1103-1137 (_routeFeesToProject), specifically 1103-1105 (fee terminal lookup)
+- **Description:** If the fee project's primary terminal for the terminal token is removed or changed to `address(0)`, the fee routing silently skips the fee payment (line 1105: `if (feeTerminal != address(0))`). The `feeAmount` is computed (line 1098) but never transferred. The terminal token fee amount is retained in the contract and eventually gets absorbed into the next liquidity operation.
+- **Mitigation:** The `initialize` validation (line 184-188) checks that the fee project has a controller at initialization time. However, the terminal could be removed later. This is a graceful degradation -- the project's share (`remainingAmount`) is still routed correctly.
+
+### Severity: LOW
+
+#### L-1. Implementation Contract Initializable
+
+- **Tested:** `M32_ReinitAfterRenounce.t.sol` tests clone re-initialization prevention.
+- **Lines:** 177-194 (initialize)
+- **Description:** The implementation contract deployed by the factory never calls `initialize` in its constructor. Anyone can call `initialize()` on the implementation with arbitrary parameters. This has no practical impact because clones have separate storage, and the implementation is not used directly.
+
+#### L-2. processSplitWith Burns for All Terminal Tokens After First Pool
+
+- **Tested:** `UniV4DeploymentSplitHook_AuditFindings.t.sol` (test_M2_processSplitWith_burnsAfterDeploy, test_M2_multiTerminalToken_independentFlags).
+- **Lines:** 545 (deployedPoolCount check), 134 (deployedPoolCount mapping)
+- **Description:** `processSplitWith` uses `deployedPoolCount[projectId]` (per-project, not per-terminal-token) to decide whether to accumulate or burn (line 545). Once any pool is deployed for a project, all subsequent reserved token splits burn tokens. This prevents accumulation for a second terminal token's pool. The `JBSplitHookContext` does not include the terminal token, so per-token accumulation is not possible with the current interface.
+- **Mitigation:** This is a known architectural constraint. To deploy pools for multiple terminal tokens, the project must deploy separate hook clones.
+
+#### L-3. Irreversible Pool Deployment
+
+- **Tested:** `DeploymentStageTest.t.sol` (test_DeployPool_RevertsIf_PoolAlreadyDeployed).
+- **Lines:** 514 (PoolAlreadyDeployed check), 527 (projectDeployed set to true)
+- **Description:** Once `deployPool` succeeds, there is no way to undeploy, reconfigure, or redeploy the pool for the same project/terminal-token pair. The `projectDeployed` flag is a one-way latch. If the pool is deployed at a suboptimal price or with wrong parameters, the only remedy is `rebalanceLiquidity` (which adjusts tick bounds but cannot change the pool's fee tier, hook address, or currency pair).
+
+#### L-4. Rounding in Fee Split Arithmetic
+
+- **Tested:** `FeeRoutingTest.t.sol` (test_RouteFees_SplitsBetweenFeeAndOriginal) tests the split with 1000e18.
+- **Lines:** 1098 (fee calculation: `feeAmount = (amount * FEE_PERCENT) / BPS`)
+- **Description:** Integer division truncates in favor of the original project (the fee project receives slightly less). For a 38% fee with an amount of `N`, the fee project receives `floor(N * 3800 / 10000)` and the project receives `N - floor(N * 3800 / 10000)`. The rounding error is at most 1 wei per fee routing operation. This matches the Juicebox core convention.
+
+#### L-5. No Reentrancy Guard
+
+- **Tested:** `SecurityTest.t.sol` (test_ClaimFeeTokens_ClearsBeforeTransfer) verifies the checks-effects-interactions pattern for `claimFeeTokensFor`.
+- **Lines:** 448-449 (claimFeeTokensFor: zeroes balance before transfer), 724-733 (deployPool: external call to terminal.cashOutTokensOf)
+- **Description:** The contract has no explicit `ReentrancyGuard`. It relies on state ordering: `claimFeeTokensFor` zeroes `claimableFeeTokens` before the `safeTransfer` (line 449 before 453). `deployPool` and `rebalanceLiquidity` make multiple external calls (to `PositionManager`, `terminal.cashOutTokensOf`, `terminal.pay`, `addToBalanceOf`). The state is generally updated before external calls, but the call chains are complex. Reentrancy through V4 PositionManager callbacks is theoretically possible but requires a malicious PoolManager or hook contract (both of which are immutable and trusted).
+- **Mitigation:** The trust model assumes V4 infrastructure is not malicious. JB terminal calls use try-catch internally. The `processSplitWith` function validates `msg.sender == controllerOf(projectId)` (line 539), preventing reentrancy through the split hook interface.
+
+#### L-6. Permissionless Fee Collection Timing
+
+- **Tested:** `SecurityTest.t.sol` (test_CollectFees_Permissionless).
+- **Lines:** 459-488 (collectAndRouteLPFees, no access control)
+- **Description:** Anyone can trigger `collectAndRouteLPFees` at any time. While this is a feature (enabling keepers), it means an adversary can time fee collection to their advantage. For example, collecting fees just before a large swap (when the pool price is at one extreme) versus after. The practical impact is minimal because fee collection does not change the pool price -- it only harvests accrued swap fees.
+
+## Concrete Attack Scenarios
+
+### Scenario 1: Rebalance Sandwich (H-1)
+
+**Attacker:** MEV bot monitoring the mempool.
+**Cost:** Gas + swap fees (1% per swap in the V4 pool).
+**Profit potential:** Proportional to position size and price impact achievable.
+
+```
+1. Observe pending rebalanceLiquidity(projectId, ETH, 0, 0, 0, 0) in mempool
+2. Front-run: Swap large amount of project tokens into the pool, pushing price down
+3. rebalanceLiquidity executes:
+   - BURN_POSITION returns skewed amounts (mostly project tokens)
+   - New tick bounds computed from current Juicebox rates (not the pool price)
+   - MINT_POSITION creates position at new bounds with skewed amounts
+4. Back-run: Swap back, buying cheap project tokens from the new position
+```
+
+**Defense:** Set non-zero slippage parameters. Use Flashbots or private mempool. The 1% fee tier makes each swap leg expensive.
+
+### Scenario 2: Stale Owner Blocks Pool Deployment (M-3)
+
+**Attacker:** Project owner who loses keys or becomes unresponsive.
+**Timeline:** Until weight decays 10x from `initialWeightOf`.
+
+```
+1. Project accumulates tokens via reserved splits
+2. Owner never calls deployPool
+3. Tokens sit idle, losing value as issuance rate decays
+4. Eventually (after enough ruleset cycles with weight cut), weight drops below 1/10th
+5. Anyone can call deployPool permissionlessly
+```
+
+**Defense:** Built into the protocol. The 10x decay threshold (line 506) ensures eventual permissionless deployment. For a project with 80% weight cut per cycle and 1-day duration, this takes approximately 3 days (confirmed in `Fork.t.sol` test_fork_deployPool_permissionlessAfterWeightDecay).
+
+### Scenario 3: Initial Price Front-Running (M-2)
+
+**Attacker:** Anyone who can pay into the project.
+**Cost:** JB protocol fees (2.5%) on the pay-in amount.
+
+```
+1. Observe pending deployPool transaction
+2. Front-run: Pay large amount into the project to inflate surplus
+3. deployPool executes with inflated cashout rate, creating pool at wrong price
+4. Back-run: Cash out to reclaim most of the paid amount
+5. Arbitrage the mispriced pool
+```
+
+**Defense:** The 2.5% JB protocol fee on payments makes this expensive. The `minCashOutReturn` parameter limits how much value can be extracted during the pool's initial cash-out. Concentrated liquidity's narrow range limits the total arbitrageable amount.
+
+## Test Coverage Analysis
+
+### Well-Tested Areas
+
+| Area | Test Files | Coverage |
+|------|-----------|----------|
+| Access control (processSplitWith) | SecurityTest, AccumulationStageTest | Comprehensive: controller-only, wrong hook, wrong groupId, invalid project |
+| Access control (deployPool) | DeploymentStageTest, WeightDecayDeployTest, SecurityTest | Comprehensive: unauthorized, owner, operator, weight-decay permissionless, edge cases |
+| Access control (rebalanceLiquidity) | AuditFindingsTest, RebalanceTest | Comprehensive: unauthorized reverts, owner succeeds, operator succeeds, zero-liquidity revert |
+| Access control (claimFeeTokensFor) | SecurityTest, FeeRoutingTest | Comprehensive: valid operator, invalid operator, zero-balance no-op |
+| Fee routing arithmetic | FeeRoutingTest | Thorough: 38/62 split verified, zero-fee no-op, claimable tracking, event emission |
+| Accumulation mechanics | AccumulationStageTest | Thorough: single, multiple, zero-amount, cross-project isolation |
+| Pool deployment lifecycle | DeploymentStageTest, IntegrationLifecycle | Thorough: creates pool, sets tokenId, clears accumulated, handles leftovers |
+| Price math | PriceMathTest | Thorough: issuance rate (0/10/100% reserved), cashout rate (0/positive surplus), sqrtPriceX96, tick bounds, alignment, geometric mean, optimal cashout |
+| Native ETH handling | NativeETHTest | Good: isNativeToken, receive(), accounting setup, end-to-end deploy with NATIVE_TOKEN |
+| Clone deployment | DeployerTest | Good: CREATE, CREATE2, address registry, initialization, events |
+| Re-initialization prevention | M32_ReinitAfterRenounce, ConstructorTest | Good: double-init reverts, initialized flag |
+| Fork integration | Fork.t.sol | Good: real V4 contracts, full lifecycle with real JB core, weight-decay permissionless deploy |
+| Token conservation | PositionManagerIntegrationTest | Good: token flows, no creation from thin air, partial usage with sweep |
+
+### Untested or Lightly Tested Areas
+
+| Area | Gap | Risk Level |
+|------|-----|------------|
+| MEV/sandwich attacks | No simulation of front-running or back-running around rebalance/collect operations | HIGH |
+| Extreme price scenarios | No tests for MIN_TICK/MAX_TICK boundaries in production conditions | LOW |
+| Fee-on-transfer tokens | No tests with non-standard ERC-20 tokens (not applicable -- JB project tokens are standard) | N/A |
+| Concurrent multi-project rebalance | No tests for multiple projects rebalancing in the same block | LOW |
+| V4 PositionManager edge cases | Mock-based tests do not cover real PositionManager revert conditions (e.g., insufficient pool liquidity for burn) | MEDIUM |
+| Gas limits | No tests for gas consumption with large accumulated balances or many fee collection cycles | LOW |
+
+## Privileged Roles
+
+| Role | Permission | Scope |
+|------|-----------|-------|
+| Project owner | `SET_BUYBACK_POOL` -- deploy pool, rebalance, claim fees | Per-project |
+| Authorized operator | `SET_BUYBACK_POOL` -- same as owner when granted | Per-project, delegated |
+| Anyone (post-10x-decay) | `deployPool` -- bypasses permission check | Per-project, conditional |
+| Anyone (post-deployment) | `collectAndRouteLPFees` -- trigger fee collection | Permissionless |
+| JB Controller | `processSplitWith` -- send tokens to hook | System role, per-project |

package/SKILLS.md

@@ -23,7 +23,7 @@ Juicebox reserved-token split hook that accumulates project tokens, deploys a Un
 
 | Function | What it does |
 |----------|-------------|
-| `deployPool(projectId, terminalToken, amount0Min, amount1Min, minCashOutReturn)` | Requires `SET_BUYBACK_POOL` permission. Creates V4 pool at geometric mean of [cashOut, issuance] rates. Computes optimal cash-out fraction, cashes out tokens via terminal, mints concentrated LP position, handles leftovers (burns project tokens, adds terminal tokens to project balance). Sets `projectDeployed = true`. |
+| `deployPool(projectId, terminalToken, amount0Min, amount1Min, minCashOutReturn)` | Requires `SET_BUYBACK_POOL` permission unless the current ruleset's weight has decayed to 1/10th or less of `initialWeightOf[projectId]` (becomes permissionless). Creates V4 pool at geometric mean of [cashOut, issuance] rates. Computes optimal cash-out fraction, cashes out tokens via terminal, mints concentrated LP position, handles leftovers (burns project tokens, adds terminal tokens to project balance). Sets `projectDeployed = true`. |
 
 ### Fee Management
 
@@ -125,6 +125,7 @@ Juicebox reserved-token split hook that accumulates project tokens, deploys a Un
 | `_poolKeys` | `projectId => terminalToken => PoolKey` | V4 pool key per project/token pair |
 | `tokenIdOf` | `projectId => terminalToken => uint256` | V4 PositionManager NFT ID per pool |
 | `accumulatedProjectTokens` | `projectId => uint256` | Pre-deployment token accumulation |
+| `initialWeightOf` | `projectId => uint256` | Ruleset weight when first tokens were accumulated (for 10x decay check) |
 | `projectDeployed` | `projectId => bool` | Switches accumulate (Stage 1) to burn (Stage 2) |
 | `claimableFeeTokens` | `projectId => uint256` | Fee-project tokens claimable via `claimFeeTokensFor` |
 | `initialized` | `bool` | Prevents re-initialization of clone instances |
@@ -134,14 +135,14 @@ Juicebox reserved-token split hook that accumulates project tokens, deploys a Un
 1. **This is a V4 hook, not V3.** Despite the repo history, the current implementation uses Uniswap V4 (`IPoolManager`, `IPositionManager`, `PoolKey`, `Actions`). All V3 references in older docs are outdated.
 2. **Requires `via_ir = true` in foundry.toml.** Stack-too-deep errors occur without the IR pipeline, particularly in `_addUniswapLiquidity` and V4 `PositionManager` interactions.
 3. **Only accepts reserved-token splits (`groupId == 1`).** Reverts with `TerminalTokensNotAllowed` if called from a payout split (`groupId == 0`). This is intentional -- it only manages project tokens.
-4. **`deployPool` requires `SET_BUYBACK_POOL` permission.** The caller must be the project owner or have been granted this permission via `JBPermissions`.
+4. **`deployPool` requires `SET_BUYBACK_POOL` permission, unless weight has decayed 10x.** The caller must be the project owner or have been granted this permission via `JBPermissions`. However, if the current ruleset's weight has decayed to 1/10th or less of the weight when the hook first started accumulating tokens (`initialWeightOf`), anyone can call `deployPool`. This prevents a stale owner from blocking LP deployment indefinitely.
 5. **`collectAndRouteLPFees` and `rebalanceLiquidity` are permissionless.** Anyone can call them. Safe because they only operate on existing positions and route funds to verified project terminals.
 6. **`claimFeeTokensFor` requires `SET_BUYBACK_POOL` permission** from the project owner. It validates the caller, not the beneficiary.
 7. **Cash-out fraction is geometrically optimized, not 50/50.** `_computeOptimalCashOutAmount` uses concentrated liquidity math to compute the exact ratio needed, typically 15-30%. Safety-capped at 50%.
 8. **Pool initialization price is the geometric mean** of [cashOutRate, issuanceRate] in tick space. Falls back to issuance rate if cash-out rate is 0 or ticks are equal.
 9. **One LP position per project/terminal-token pair.** The hook manages a single V4 NFT position. Rebalancing burns the old NFT and mints a new one, briefly leaving no active position.
 10. **After deployment, newly received reserved tokens are burned.** This is intentional -- prevents inflating the project token supply without corresponding LP rebalancing.
-11. **Native ETH handling:** Juicebox uses `JBConstants.NATIVE_TOKEN` (`0x...EEEe`), V4 uses `Currency.wrap(address(0))`. The hook converts between them via `_toCurrency()`. The contract has `receive() external payable {}` to accept ETH during cash-outs and V4 TAKE operations.
+11. **Native ETH handling:** Juicebox uses `JBConstants.NATIVE_TOKEN` (`0x000000000000000000000000000000000000EEEe`), V4 uses `Currency.wrap(address(0))`. The hook converts between them via `_toCurrency()`. The contract has `receive() external payable {}` to accept ETH during cash-outs and V4 TAKE operations.
 12. **Deployed as clones via factory.** `UniV4DeploymentSplitHookDeployer` uses Solady's `LibClone`. The constructor sets shared infrastructure (directory, tokens, V4 contracts). Per-clone config (fee project, fee percent) is set via `initialize()`, which can only be called once.
 13. **Tick alignment:** All ticks are aligned to `TICK_SPACING = 200`. Negative ticks use floor semantics in `_alignTickToSpacing()`.
 14. **`minCashOutReturn = 0` defaults to 1% tolerance.** If no minimum is specified for `deployPool`, the hook applies a 1% slippage tolerance on the cash-out automatically.