@bananapus/buyback-hook-v6 0.0.5 → 0.0.7

package/README.md

@@ -1,16 +1,16 @@
-# nana-buyback-hook-v5
+# Juicebox Buyback Hook
 
-A Juicebox data hook and pay hook that automatically routes payments through the better of two paths: minting new project tokens from the terminal, or buying them from a Uniswap V3 pool -- whichever yields more tokens for the beneficiary. The project's reserved rate applies to either route.
+A Juicebox data hook and pay hook that automatically routes payments through the better of two paths: minting new project tokens from the terminal, or buying them from a Uniswap V4 pool -- whichever yields more tokens for the beneficiary. The project's reserved rate applies to either route.
 
-_If you're having trouble understanding this contract, take a look at the [core protocol contracts](https://github.com/Bananapus/nana-core) and the [documentation](https://docs.juicebox.money/) first. If you have questions, reach out on [Discord](https://discord.com/invite/ErQYmth4dS)._
+_If you're having trouble understanding this contract, take a look at the [core protocol contracts](https://github.com/Bananapus/nana-core-v6) and the [documentation](https://docs.juicebox.money/) first. If you have questions, reach out on [Discord](https://discord.com/invite/ErQYmth4dS)._
 
 ## Architecture
 
 | Contract | Description |
 |----------|-------------|
-| `JBBuybackHook` | Core hook. Implements `IJBRulesetDataHook` (checked before recording payment) and `IJBPayHook` (executed after). Compares the terminal's mint rate against a Uniswap V3 swap quote and takes the better route. Swapped tokens are burned, then re-minted through the controller to apply the reserved rate uniformly. |
-| `JBBuybackHookRegistry` | A proxy data hook that delegates `beforePayRecordedWith` to a per-project or default `JBBuybackHook` instance. Allows project owners to choose (and lock) which buyback hook implementation they use. |
-| `JBSwapLib` | Shared library for slippage tolerance and price limit calculations. Uses a continuous sigmoid formula for smooth dynamic slippage across all swap sizes. |
+| `JBBuybackHook` | Core hook. Implements `IJBRulesetDataHook` (checked before recording payment), `IJBPayHook` (executed after), and `IUnlockCallback` (Uniswap V4 swap settlement). Compares the terminal's mint rate against a Uniswap V4 swap quote and takes the better route. Swapped tokens are burned, then re-minted through the controller to apply the reserved rate uniformly. |
+| `JBBuybackHookRegistry` | A proxy data hook that delegates `beforePayRecordedWith` to a per-project or default `JBBuybackHook` instance. The registry owner manages an allowlist of hook implementations. Project owners choose (and can permanently lock) which buyback hook their project uses. |
+| `JBSwapLib` | Shared library for oracle queries, slippage tolerance, price impact estimation, and `sqrtPriceLimitX96` calculations. Uses a continuous sigmoid formula for smooth dynamic slippage across all swap sizes. |
 
 ## How It Works
 
@@ -18,45 +18,57 @@ _If you're having trouble understanding this contract, take a look at the [core
 sequenceDiagram
     participant Terminal
     participant Buyback hook
-    participant Uniswap pool
+    participant V4 PoolManager
     participant Controller
     Note right of Terminal: User calls pay(...) to pay the project
     Terminal->>Buyback hook: Calls beforePayRecordedWith(...) with payment data
     Buyback hook->>Terminal: If swap is better: weight=0, pay hook specification
     Terminal->>Buyback hook: Calls afterPayRecordedWith(...) with specification
-    Buyback hook->>Uniswap pool: Executes swap
+    Buyback hook->>V4 PoolManager: unlock() -> unlockCallback() executes swap
     Buyback hook->>Controller: Burns swapped tokens, re-mints with reserved rate
 ```
 
 1. A payment is made to a project's terminal.
 2. The terminal calls `beforePayRecordedWith(context)` on the data hook (this contract).
 3. The hook calculates how many tokens the payer would get by minting directly (`weight * amount / weightRatio`).
-4. It compares that against a Uniswap V3 quote (user-provided or TWAP-derived with sigmoid slippage tolerance).
+4. It compares that against a Uniswap V4 quote. The TWAP-based quote uses the pool's oracle hook (if available) or falls back to spot price, then applies sigmoid-based slippage tolerance. The payer/frontend can also supply their own quote in metadata -- the hook uses whichever is higher (more protective).
 5. If the swap yields more tokens, the hook returns `weight = 0` and specifies itself as a pay hook with the swap amount.
 6. The terminal calls `afterPayRecordedWith(context)` on the pay hook.
-7. The hook executes the swap, burns the received project tokens, adds any leftover terminal tokens back to the project's balance, and mints the total (swapped + leftover mint) through the controller with `useReservedPercent: true`.
+7. The hook executes the swap via `POOL_MANAGER.unlock()`, burns the received project tokens, adds any leftover terminal tokens back to the project's balance, and mints the total (swapped + leftover mint) through the controller with `useReservedPercent: true`.
 
-If the swap fails (slippage, insufficient liquidity, etc.), the hook reverts, and the terminal's default minting behavior takes over.
+If the swap fails (slippage, insufficient liquidity, etc.), `_swap` catches the revert and returns 0, which causes `afterPayRecordedWith` to revert with `JBBuybackHook_SpecifiedSlippageExceeded`. The terminal then falls back to its default minting behavior.
+
+## Registry
+
+The `JBBuybackHookRegistry` sits between the terminal and individual hook implementations:
+
+- **Owner-managed allowlist**: The registry owner calls `allowHook(hook)` / `disallowHook(hook)` to control which implementations projects can use.
+- **Default hook**: The owner calls `setDefaultHook(hook)` to set the fallback for projects that have not explicitly chosen one. Setting a default also adds it to the allowlist.
+- **Per-project override**: Project owners call `setHookFor(projectId, hook)` to select an allowed hook. Permission: `SET_BUYBACK_HOOK` (ID 27).
+- **Locking**: Project owners call `lockHookFor(projectId)` to permanently freeze their hook choice. Once locked, the hook cannot be changed. Same permission: `SET_BUYBACK_HOOK` (ID 27). Locking requires a non-zero hook (either explicitly set or inherited from default). If the project is using the default, locking snapshots that default into the project's storage.
+- **Mint permission delegation**: `hasMintPermissionFor` returns `true` only for the address of the hook active for the project, enabling the hook to mint tokens through the controller.
+
+When `disallowHook` removes a hook that is currently the default, the default is also cleared.
 
 ## Install
 
 For projects using `npm` to manage dependencies (recommended):
 
 ```bash
-npm install @bananapus/buyback-hook
+npm install @bananapus/buyback-hook-v6
 ```
 
 For projects using `forge` to manage dependencies:
 
 ```bash
-forge install Bananapus/nana-buyback-hook
+forge install Bananapus/nana-buyback-hook-v6
 ```
 
-If you're using `forge`, add `@bananapus/buyback-hook/=lib/nana-buyback-hook/` to `remappings.txt`.
+If you're using `forge`, add `@bananapus/buyback-hook-v6/=lib/nana-buyback-hook-v6/` to `remappings.txt`.
 
 ## Develop
 
-`nana-buyback-hook` uses [npm](https://www.npmjs.com/) (version >=20.0.0) for package management and [Foundry](https://github.com/foundry-rs/foundry) for builds and tests.
+`nana-buyback-hook-v6` uses [npm](https://www.npmjs.com/) (version >=20.0.0) for package management and [Foundry](https://github.com/foundry-rs/foundry) for builds and tests.
 
 ```bash
 npm ci && forge install
@@ -83,71 +95,113 @@ npm ci && forge install
 
 Key `foundry.toml` settings:
 
-- `solc = '0.8.23'`
-- `evm_version = 'paris'` (L2-compatible)
+- `solc = '0.8.26'`
+- `evm_version = 'cancun'` (required for Uniswap V4's transient storage `TSTORE`/`TLOAD`)
 - `optimizer_runs = 100000000`
-- `fuzz.runs = 16384`
+- `fuzz.runs = 4096`
 
 ## Repository Layout
 
 ```
-nana-buyback-hook-v5/
+nana-buyback-hook-v6/
 ├── src/
-│   ├── JBBuybackHook.sol             # Core buyback hook (data hook + pay hook)
-│   ├── JBBuybackHookRegistry.sol     # Per-project hook routing
+│   ├── JBBuybackHook.sol             # Core buyback hook (data hook + pay hook + V4 unlock callback)
+│   ├── JBBuybackHookRegistry.sol     # Per-project hook routing with allowlist and locking
 │   ├── libraries/
-│   │   └── JBSwapLib.sol             # Slippage tolerance + price limit calculations
+│   │   └── JBSwapLib.sol             # Oracle queries, slippage tolerance, price limit calculations
 │   └── interfaces/
 │       ├── IJBBuybackHook.sol        # Buyback hook interface
 │       ├── IJBBuybackHookRegistry.sol # Registry interface
+│       ├── IGeomeanOracle.sol        # V4 oracle hook interface (TWAP observation)
 │       └── external/
 │           └── IWETH9.sol            # WETH wrapper interface
 ├── script/
-│   └── Deploy.s.sol                  # Deployment script
+│   └── Deploy.s.sol                  # Multi-chain deployment script (Ethereum, Optimism, Base, Arbitrum)
 └── test/
-    ├── Fork.t.sol                    # Fork tests
-    └── helpers/                      # Test helpers
+    ├── V4BuybackHook.t.sol           # Core hook unit tests
+    ├── Registry.t.sol                # Registry unit tests
+    ├── JBSwapLib.t.sol               # Library unit tests
+    ├── MEVScenarios.t.sol            # MEV attack scenario tests
+    ├── fork/
+    │   └── V4ForkTest.t.sol          # Mainnet fork integration tests
+    └── mock/
+        ├── MockOracleHook.sol        # Configurable TWAP oracle mock
+        ├── MockPoolManager.sol       # V4 PoolManager mock
+        └── MockSplitHook.sol         # Split hook mock
 ```
 
 ## Project Owner Usage Guide
 
 ### Setting The Pool
 
-Call `setPoolFor(projectId, fee, twapWindow, terminalToken)` to configure the Uniswap V3 pool for your project. This can only be called once per terminal token.
+Call `setPoolFor(projectId, poolKey, twapWindow, terminalToken)` to configure the Uniswap V4 pool for your project. This can only be called once per terminal token -- pool assignments are immutable once set to prevent swap routing manipulation.
 
-- The `fee` is a `uint24` with the same representation as Uniswap (basis points with 2 decimals): 0.01% = `100`, 0.05% = `500`, 0.3% = `3000`, 1% = `10000`.
-- If using ETH, pass `JBConstants.NATIVE_TOKEN` (`0x000000000000000000000000000000000000EEEe`) as `terminalToken`.
-- The pool address is computed via create2 using Uniswap V3's canonical init code hash.
+- `poolKey` is a Uniswap V4 `PoolKey` struct containing `currency0`, `currency1`, `fee`, `tickSpacing`, and `hooks`. The pool must already be initialized in the V4 PoolManager.
+- The `PoolKey` currencies must match the project token and the terminal token (in either order). The hook validates this on-chain.
+- If using ETH, pass `JBConstants.NATIVE_TOKEN` (`0x000000000000000000000000000000000000EEEe`) as `terminalToken`. The hook normalizes this to WETH internally.
+- The project must have already issued an ERC-20 token (via `JBTokens`).
+- Permission: `SET_BUYBACK_POOL` (ID 26).
 
 ### Setting TWAP Parameters
 
 The TWAP window controls the time period over which the time-weighted average price is computed. A shorter window gives more accurate data but is easier to manipulate; a longer window is more stable but can lag during high volatility.
 
-- Call `setTwapWindowOf(projectId, newWindow)` to change the TWAP window (min: 2 minutes, max: 2 days).
+- Call `setTwapWindowOf(projectId, newWindow)` to change the TWAP window (min: 5 minutes, max: 2 days).
 - A 30-minute window is a good starting point for high-activity pairs.
+- Permission: `SET_BUYBACK_TWAP` (ID 25).
+- The TWAP window is shared across all pools for the same project.
+
+### Oracle Behavior
+
+The hook queries the pool's oracle hook (if any) via the `IGeomeanOracle.observe` interface for TWAP data. If the oracle hook reverts or is not available, the hook falls back to the pool's current spot price and in-range liquidity from the PoolManager.
+
+When the oracle returns zero liquidity, the hook returns 0 for the quote, which causes it to fall back to minting rather than swapping -- protecting against swaps in pools with no liquidity.
 
 ### Slippage Tolerance
 
 The buyback hook uses a continuous sigmoid formula (`JBSwapLib.getSlippageTolerance`) to dynamically calculate slippage tolerance based on the estimated price impact of the swap:
 
-- Small swaps in deep pools get ~2% tolerance.
+- Small swaps in deep pools get ~2% tolerance (minimum floor).
 - Large swaps relative to pool liquidity approach the 88% ceiling.
-- The minimum tolerance is the pool fee + 1% (floor of 2%).
+- The minimum tolerance is the pool fee + 1% buffer (with an absolute floor of 2%).
+- If the calculated slippage tolerance hits the 88% maximum, the hook returns 0 (triggers mint fallback) rather than attempting a swap with extreme slippage.
 
 ### Avoiding MEV
 
-Payers/frontends should provide a reasonable minimum quote in metadata to protect against MEV. You can also use the [Flashbots Protect RPC](https://protect.flashbots.net/) for transactions that trigger the buyback hook.
+The hook provides two layers of MEV protection:
+
+1. **sqrtPriceLimitX96**: The V4 swap is executed with a price limit computed from the minimum acceptable output (`JBSwapLib.sqrtPriceLimitFromAmounts`). This stops the swap early if the price moves unfavorably, rather than executing at a bad rate.
+2. **Quote floor**: The hook always takes the higher of the payer's quote and the TWAP-based quote. A stale or manipulated payer quote cannot produce a worse deal than what the oracle suggests.
+
+Payers/frontends should provide a reasonable minimum quote in metadata for additional protection. You can also use the [Flashbots Protect RPC](https://protect.flashbots.net/) for transactions that trigger the buyback hook.
 
 ## Payment Metadata
 
-The hook reads metadata with key `"quote"`, encoding `(uint256 amountToSwapWith, uint256 minimumSwapAmountOut)`:
+The hook reads metadata with key `"quote"` (resolved via `JBMetadataResolver`), encoding `(uint256 amountToSwapWith, uint256 minimumSwapAmountOut)`:
 
 - If `amountToSwapWith == 0`, the full payment amount is used for the swap.
-- If `minimumSwapAmountOut == 0`, a TWAP-based quote is calculated with sigmoid slippage tolerance.
+- If `amountToSwapWith > 0`, only that portion is swapped and the remainder is minted directly.
+- If `amountToSwapWith > totalPaid`, the transaction reverts with `JBBuybackHook_InsufficientPayAmount`.
+- The `minimumSwapAmountOut` is compared against the TWAP-derived minimum -- the higher value is used.
+
+## Supported Chains
+
+The deployment script (`Deploy.s.sol`) supports:
+
+| Chain | WETH | PoolManager |
+|-------|------|-------------|
+| Ethereum Mainnet | `0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2` | `0x000000000004444c5dc75cB358380D2e3dE08A90` |
+| Optimism | `0x4200000000000000000000000000000000000006` | `0x9a13f98cb987694c9f086b1f5eb990eea8264ec3` |
+| Base | `0x4200000000000000000000000000000000000006` | `0x498581ff718922c3f8e6a244956af099b2652b2b` |
+| Arbitrum | `0x82aF49447D8a07e3bd95BD0d56f35241523fBab1` | `0x360e68faccca8ca495c1b759fd9eee466db9fb32` |
+
+Sepolia testnets for all four chains are also supported.
 
 ## Risks
 
-- The hook depends on liquidity in a Uniswap V3 pool. If liquidity migrates to a new pool, the project owner must call `setPoolFor(...)`. If liquidity migrates to a different exchange or Uniswap version, a new hook deployment is needed.
-- `setPoolFor` can only be called once per project + terminal token pair. Once set, the pool cannot be changed.
+- The hook depends on liquidity in a Uniswap V4 pool. If liquidity migrates to a new pool with different `PoolKey` parameters (different fee, tickSpacing, or hooks), the hook cannot be redirected -- pool assignments are immutable once set via `setPoolFor`.
+- `setPoolFor` can only be called once per project + terminal token pair. If you need to use a different pool, a new hook deployment is needed.
 - If the TWAP window isn't set appropriately, payers may receive fewer tokens than expected.
 - Low liquidity pools are vulnerable to TWAP manipulation by attackers.
+- If the pool's oracle hook is absent or reverts, the hook falls back to spot price, which is more susceptible to manipulation.
+- The registry's `lockHookFor` is irreversible. Once locked, the project cannot change its hook implementation even if a security issue is found in that implementation.

package/SKILLS.md

@@ -1,96 +1,195 @@
-# nana-buyback-hook-v5
+# Juicebox Buyback Hook
 
 ## Purpose
 
-Route project payments through the better of two paths -- minting from the terminal or buying from a Uniswap V3 pool -- to maximize tokens received by the beneficiary while preserving the reserved rate.
+Route project payments through the better of two paths -- minting from the terminal or buying from a Uniswap V4 pool -- to maximize tokens received by the beneficiary while preserving the reserved rate.
 
 ## Contracts
 
 | Contract | Role |
 |----------|------|
-| `JBBuybackHook` | Core hook: implements `IJBRulesetDataHook` + `IJBPayHook` + `IUniswapV3SwapCallback`. Compares mint vs swap, executes the better route, burns swapped tokens, re-mints through controller with reserved rate. |
-| `JBBuybackHookRegistry` | Proxy data hook routing `beforePayRecordedWith` to a per-project or default `JBBuybackHook`. Allows project owners to choose and lock implementations. |
-| `JBSwapLib` | Library for computing sigmoid-based slippage tolerance and `sqrtPriceLimitX96` from input/output amounts. |
+| `JBBuybackHook` | Core hook: implements `IJBRulesetDataHook` + `IJBPayHook` + `IUnlockCallback`. Compares mint vs swap via TWAP oracle or spot price, executes the better route through V4 PoolManager, burns swapped tokens, re-mints through controller with reserved rate. |
+| `JBBuybackHookRegistry` | Proxy data hook with allowlist. Routes `beforePayRecordedWith` to a per-project or default `JBBuybackHook`. Project owners choose, and optionally lock, implementations. Registry owner manages the allowlist. |
+| `JBSwapLib` | Library for oracle queries (TWAP or spot), sigmoid-based slippage tolerance, price impact estimation, tick-to-price conversion, and `sqrtPriceLimitX96` computation. |
 
 ## Key Functions
 
-| Function | Contract | What it does |
-|----------|----------|--------------|
-| `beforePayRecordedWith(context)` | `JBBuybackHook` | Data hook: compares mint count vs swap quote. If swap is better, returns `weight=0` and a `JBPayHookSpecification` targeting itself. If mint is better, returns original weight (no hook). |
-| `afterPayRecordedWith(context)` | `JBBuybackHook` | Pay hook: pulls tokens from terminal, executes Uniswap V3 swap, burns swapped tokens, returns leftover to project balance, mints total (swapped + leftover mint) via controller with `useReservedPercent: true`. |
-| `setPoolFor(projectId, fee, twapWindow, terminalToken)` | `JBBuybackHook` | Set the Uniswap V3 pool for a project+terminal token pair. Computes pool address via create2. Stores pool, TWAP window, and project token. Permission: `SET_BUYBACK_POOL`. |
-| `setTwapWindowOf(projectId, newWindow)` | `JBBuybackHook` | Change the TWAP window for a project (2 min to 2 days). Permission: `SET_BUYBACK_TWAP`. |
-| `uniswapV3SwapCallback(amount0Delta, amount1Delta, data)` | `JBBuybackHook` | Uniswap V3 callback: validates caller is the expected pool, wraps native tokens if needed, transfers input tokens to the pool. |
-| `beforeCashOutRecordedWith(context)` | `JBBuybackHook` | Pass-through: returns cash-out context unchanged (buyback only applies to payments). |
-| `hasMintPermissionFor(projectId, ruleset, addr)` | `JBBuybackHook` | Returns `false` (the hook itself does not claim mint permission). |
-| `setHookFor(projectId, hook)` | `JBBuybackHookRegistry` | Route a project to a specific allowed buyback hook. Permission: `SET_BUYBACK_POOL`. |
-| `lockHookFor(projectId)` | `JBBuybackHookRegistry` | Lock the hook choice for a project (irreversible). |
-| `hasMintPermissionFor(projectId, ruleset, addr)` | `JBBuybackHookRegistry` | Returns `true` only if `addr` is the hook registered for the project. |
+### JBBuybackHook
+
+| Function | What it does |
+|----------|--------------|
+| `beforePayRecordedWith(context)` | Data hook (view): compares mint count vs swap quote. Reads `"quote"` metadata for payer-supplied `(amountToSwapWith, minimumSwapAmountOut)`. Computes TWAP-based minimum and uses the higher of the two. If swap yields more tokens, returns `weight=0` and a `JBPayHookSpecification` targeting itself. If mint is better, returns original weight (no hook). |
+| `afterPayRecordedWith(context)` | Pay hook: pulls tokens from terminal, executes V4 swap via `POOL_MANAGER.unlock()`, burns swapped tokens, returns leftover to project balance via `addToBalanceOf`, mints total (swapped + leftover mint) via `controller.mintTokensOf` with `useReservedPercent: true`. Reverts with `JBBuybackHook_SpecifiedSlippageExceeded` if swap output < minimum. |
+| `setPoolFor(projectId, poolKey, twapWindow, terminalToken)` | Set the V4 pool for a project+terminal token pair. Validates: pool is initialized in PoolManager, currencies match project token and terminal token, TWAP window in bounds. Stores pool key, TWAP window, and project token. **Immutable once set.** Permission: `SET_BUYBACK_POOL` (ID 26). |
+| `setTwapWindowOf(projectId, newWindow)` | Change the TWAP window for a project (5 minutes to 2 days). Permission: `SET_BUYBACK_TWAP` (ID 25). |
+| `unlockCallback(data)` | V4 PoolManager callback. Decodes `SwapCallbackData`, computes `sqrtPriceLimitX96`, executes swap, settles input tokens, takes output tokens. Only callable by PoolManager. |
+| `poolKeyOf(projectId, terminalToken)` | Returns the V4 `PoolKey` for a project+terminal token pair. |
+| `beforeCashOutRecordedWith(context)` | Pass-through: returns cash-out context unchanged (buyback only applies to payments). |
+| `hasMintPermissionFor(projectId, ruleset, addr)` | Returns `false` (the hook itself does not claim mint permission -- the registry handles this). |
+| `supportsInterface(interfaceId)` | Returns `true` for `IJBRulesetDataHook`, `IJBPayHook`, `IJBBuybackHook`, `IJBPermissioned`, `IERC165`. |
+
+### JBBuybackHookRegistry
+
+| Function | What it does |
+|----------|--------------|
+| `hookOf(projectId)` | Returns the hook for the project, falling back to `defaultHook` if none is set. |
+| `beforePayRecordedWith(context)` | Resolves the project's hook (or default) and delegates the call. |
+| `beforeCashOutRecordedWith(context)` | Pass-through: returns cash-out context unchanged. |
+| `hasMintPermissionFor(projectId, ruleset, addr)` | Returns `true` only if `addr` is the hook registered (or defaulted) for the project. |
+| `setHookFor(projectId, hook)` | Route a project to a specific allowed buyback hook. Reverts if hook is locked or not on the allowlist. Permission: `SET_BUYBACK_HOOK` (ID 27). |
+| `lockHookFor(projectId, expectedHook)` | Lock the hook choice for a project (irreversible). If using default, snapshots it into storage first. Requires a non-zero hook. Reverts with `JBBuybackHookRegistry_HookMismatch` if the resolved hook differs from `expectedHook` (prevents race conditions). Permission: `SET_BUYBACK_HOOK` (ID 27). |
+| `allowHook(hook)` | Add a hook to the allowlist. Owner only. |
+| `disallowHook(hook)` | Remove a hook from the allowlist. If the disallowed hook is the current default, also clears the default. Owner only. |
+| `setDefaultHook(hook)` | Set the default hook (also adds to allowlist). Owner only. |
+| `supportsInterface(interfaceId)` | Returns `true` for `IJBBuybackHookRegistry`, `IJBRulesetDataHook`, `IERC165`. |
 
 ## Integration Points
 
 | Dependency | Import | Used For |
 |------------|--------|----------|
 | `nana-core-v6` | `IJBDirectory`, `IJBController`, `IJBMultiTerminal` | Directory lookups (`isTerminalOf`, `controllerOf`), token minting (`mintTokensOf`), token burning (`burnTokensOf`), balance management (`addToBalanceOf`) |
-| `nana-core-v6` | `IJBPrices` | Cross-currency weight ratio when ruleset base currency differs from payment currency |
-| `nana-core-v6` | `IJBTokens`, `IJBProjects`, `IJBPermissions` | Token lookups, project ownership, permission checks (`SET_BUYBACK_POOL`, `SET_BUYBACK_TWAP`) |
+| `nana-core-v6` | `IJBPrices` | Cross-currency weight ratio when ruleset base currency differs from payment currency (`pricePerUnitOf`) |
+| `nana-core-v6` | `IJBTokens`, `IJBProjects`, `IJBPermissions` | Token lookups (`tokenOf`), project ownership (`ownerOf`), permission checks |
 | `nana-core-v6` | `JBMetadataResolver` | Parsing `"quote"` metadata key from payment calldata (contains `amountToSwapWith` and `minimumSwapAmountOut`) |
 | `nana-core-v6` | `JBRulesetMetadataResolver` | Extracting `baseCurrency()` from packed ruleset metadata |
-| `nana-permission-ids-v6` | `JBPermissionIds` | Permission ID constants |
-| `@uniswap/v3-core` | `IUniswapV3Pool`, `TickMath` | Pool swaps and tick-to-sqrtPrice conversion |
-| `@uniswap/v3-periphery` | `OracleLibrary` | TWAP oracle consultation (`consult`, `getQuoteAtTick`, `getOldestObservationSecondsAgo`) |
+| `nana-permission-ids-v6` | `JBPermissionIds` | Permission ID constants (`SET_BUYBACK_TWAP` = 25, `SET_BUYBACK_POOL` = 26, `SET_BUYBACK_HOOK` = 27) |
+| `@uniswap/v4-core` | `IPoolManager`, `IUnlockCallback`, `PoolKey`, `PoolId`, `Currency`, `BalanceDelta`, `SwapParams`, `TickMath`, `StateLibrary` | V4 pool swaps (`unlock`, `swap`, `settle`, `take`), pool state queries (`getSlot0`, `getLiquidity`), tick math |
 | `@prb/math` | `mulDiv` | Safe fixed-point multiplication |
-| `@openzeppelin/contracts` | `ERC2771Context`, `SafeERC20` | Meta-transactions, safe token transfers |
+| `@openzeppelin/contracts` | `ERC2771Context`, `SafeERC20`, `Ownable` (registry only) | Meta-transactions, safe token transfers, registry ownership |
 
 ## Key Types
 
-| Struct/Enum | Key Fields | Used In |
-|-------------|------------|---------|
+| Struct/Type | Fields | Used In |
+|-------------|--------|---------|
+| `SwapCallbackData` (internal to `JBBuybackHook`) | `key` (PoolKey), `projectTokenIs0` (bool), `amountIn` (uint256), `minimumSwapAmountOut` (uint256), `terminalToken` (address) | Encoded as `bytes` for `POOL_MANAGER.unlock()`, decoded in `unlockCallback` |
+| `PoolKey` (Uniswap V4) | `currency0` (Currency), `currency1` (Currency), `fee` (uint24), `tickSpacing` (int24), `hooks` (IHooks) | Stored per project+terminalToken in `_poolKeyOf`. Passed to `setPoolFor`. |
 | `JBBeforePayRecordedContext` | `projectId`, `amount` (token, value, decimals, currency), `weight`, `metadata` | Input to `beforePayRecordedWith` |
 | `JBAfterPayRecordedContext` | `projectId`, `forwardedAmount`, `weight`, `beneficiary`, `hookMetadata` | Input to `afterPayRecordedWith` |
-| `JBPayHookSpecification` | `hook`, `amount`, `metadata` | Returned from `beforePayRecordedWith` when swap is chosen |
+| `JBPayHookSpecification` | `hook` (IJBPayHook), `amount` (uint256), `metadata` (bytes) | Returned from `beforePayRecordedWith` when swap is chosen |
 | `JBRuleset` | `baseCurrency()` (from packed metadata) | Used for cross-currency weight adjustment |
 
 ## JBSwapLib Details
 
 | Function | What it does |
 |----------|--------------|
-| `getSlippageTolerance(impact, poolFeeBps)` | Continuous sigmoid: `minSlippage + (maxSlippage - minSlippage) * impact / (impact + K)`. Min = pool fee + 1% (floor 2%), max = 88%. K = 5e16. |
-| `calculateImpact(amountIn, liquidity, sqrtP, zeroForOne)` | Estimates price impact scaled by 1e18: `amountIn * 1e18 / liquidity`, normalized by sqrtPrice direction. |
-| `sqrtPriceLimitFromAmounts(amountIn, minimumAmountOut, zeroForOne)` | Computes a `sqrtPriceLimitX96` from the minimum acceptable swap rate. Provides MEV protection by stopping the swap if the execution price would be worse than the minimum. |
+| `getQuoteFromOracle(poolManager, key, twapWindow, amountIn, baseToken, quoteToken)` | Queries the pool's oracle hook via `IGeomeanOracle.observe` for TWAP data. If `twapWindow == 0` or the oracle reverts, falls back to spot price from `poolManager.getSlot0`. Returns `(amountOut, arithmeticMeanTick, harmonicMeanLiquidity)`. |
+| `getSlippageTolerance(impact, poolFeeBps)` | Continuous sigmoid: `minSlippage + (maxSlippage - minSlippage) * impact / (impact + K)`. Min = pool fee + 1% (floor 2%), max = 88%. K = 5e16. Returns tolerance in basis points of `SLIPPAGE_DENOMINATOR` (10,000). |
+| `calculateImpact(amountIn, liquidity, sqrtP, zeroForOne)` | Estimates price impact scaled by `IMPACT_PRECISION` (1e18): `amountIn * 1e18 / liquidity`, normalized by sqrtPrice direction. Returns 0 when liquidity or sqrtP is 0. |
+| `getQuoteAtTick(tick, baseAmount, baseToken, quoteToken)` | Converts a tick to a price and returns the equivalent quote amount. Ported from Uniswap V3 `OracleLibrary.getQuoteAtTick` -- pure math, no V3 dependency. |
+| `sqrtPriceLimitFromAmounts(amountIn, minimumAmountOut, zeroForOne)` | Computes a `sqrtPriceLimitX96` from the minimum acceptable swap rate. Provides MEV protection by stopping the swap if the execution price would be worse than the minimum. Handles extreme ratios gracefully with fallback to no limit. |
 
 ## Constants
 
 | Constant | Value | Purpose |
 |----------|-------|---------|
-| `MIN_TWAP_WINDOW` | `2 minutes` | Minimum TWAP oracle window |
-| `MAX_TWAP_WINDOW` | `2 days` | Maximum TWAP oracle window |
-| `TWAP_SLIPPAGE_DENOMINATOR` | `10,000` | Basis points denominator |
-| `UNCERTAIN_TWAP_SLIPPAGE_TOLERANCE` | `1,050` | 10.5% fallback when impact is zero |
+| `MIN_TWAP_WINDOW` | `5 minutes` (300s) | Minimum TWAP oracle window |
+| `MAX_TWAP_WINDOW` | `2 days` (172,800s) | Maximum TWAP oracle window |
+| `TWAP_SLIPPAGE_DENOMINATOR` | `10,000` | Basis points denominator for slippage |
+| `JBSwapLib.SLIPPAGE_DENOMINATOR` | `10,000` | Basis points denominator (internal to library) |
 | `JBSwapLib.MAX_SLIPPAGE` | `8,800` | 88% sigmoid ceiling |
 | `JBSwapLib.IMPACT_PRECISION` | `1e18` | Impact calculation precision |
 | `JBSwapLib.SIGMOID_K` | `5e16` | Sigmoid curve inflection point |
 
+## Permission IDs
+
+| ID | Constant | Used By | Grants |
+|----|----------|---------|--------|
+| 25 | `SET_BUYBACK_TWAP` | `JBBuybackHook.setTwapWindowOf` | Change the TWAP window for a project |
+| 26 | `SET_BUYBACK_POOL` | `JBBuybackHook.setPoolFor` | Set the V4 pool for a project+terminal token pair |
+| 27 | `SET_BUYBACK_HOOK` | `JBBuybackHookRegistry.setHookFor`, `lockHookFor` | Choose and lock the hook implementation for a project |
+
+## Events
+
+### JBBuybackHook
+
+| Event | Fields |
+|-------|--------|
+| `Swap` | `projectId` (indexed), `amountToSwapWith`, `poolId` (indexed), `amountReceived`, `caller` |
+| `Mint` | `projectId` (indexed), `leftoverAmount`, `tokenCount`, `caller` |
+| `PoolAdded` | `projectId` (indexed), `terminalToken` (indexed), `poolId`, `caller` |
+| `TwapWindowChanged` | `projectId` (indexed), `oldWindow`, `newWindow`, `caller` |
+
+### JBBuybackHookRegistry
+
+| Event | Fields |
+|-------|--------|
+| `JBBuybackHookRegistry_AllowHook` | `hook` |
+| `JBBuybackHookRegistry_DisallowHook` | `hook` |
+| `JBBuybackHookRegistry_LockHook` | `projectId` |
+| `JBBuybackHookRegistry_SetDefaultHook` | `hook` |
+| `JBBuybackHookRegistry_SetHook` | `projectId` (indexed), `hook` |
+
+## Custom Errors
+
+### JBBuybackHook
+
+| Error | When |
+|-------|------|
+| `JBBuybackHook_CallerNotPoolManager(address caller)` | `unlockCallback` called by someone other than the PoolManager |
+| `JBBuybackHook_InsufficientPayAmount(uint256 swapAmount, uint256 totalPaid)` | Metadata specifies `amountToSwapWith > totalPaid` |
+| `JBBuybackHook_InvalidTwapWindow(uint256 value, uint256 min, uint256 max)` | TWAP window outside [5 minutes, 2 days] |
+| `JBBuybackHook_PoolAlreadySet(PoolId poolId)` | `setPoolFor` called again for same project+token pair |
+| `JBBuybackHook_PoolNotInitialized(PoolId poolId)` | Pool not initialized in V4 PoolManager (sqrtPriceX96 == 0) |
+| `JBBuybackHook_SpecifiedSlippageExceeded(uint256 amount, uint256 minimum)` | Swap output less than minimum acceptable amount |
+| `JBBuybackHook_TerminalTokenIsProjectToken(address, address)` | Terminal token same as project token |
+| `JBBuybackHook_Unauthorized(address caller)` | `afterPayRecordedWith` called by non-terminal |
+| `JBBuybackHook_ZeroProjectToken()` | Project has not issued an ERC-20 token |
+| `JBBuybackHook_ZeroTerminalToken()` | Terminal token resolves to address(0) |
+
+### JBBuybackHookRegistry
+
+| Error | When |
+|-------|------|
+| `JBBuybackHookRegistry_HookLocked(uint256 projectId)` | `setHookFor` called on a locked project |
+| `JBBuybackHookRegistry_HookMismatch(IJBRulesetDataHook currentHook, IJBRulesetDataHook expectedHook)` | `lockHookFor` called but resolved hook differs from the caller's `expectedHook` |
+| `JBBuybackHookRegistry_HookNotAllowed(IJBRulesetDataHook hook)` | `setHookFor` called with a hook not on the allowlist |
+| `JBBuybackHookRegistry_HookNotSet(uint256 projectId)` | `lockHookFor` called but no hook is set and no default exists |
+| `JBBuybackHookRegistry_ZeroHook()` | `setDefaultHook` called with `address(0)` |
+
 ## Gotchas
 
-- The hook computes pool addresses via create2 (`POOL_INIT_CODE_HASH`) rather than calling the factory, so `setPoolFor` works even if the pool hasn't been deployed yet.
-- Pool addresses are computed using Uniswap V3's canonical init code hash (`0xe34f199b19b2b4f47f68442619d555527d244f78a3297ea89325f843f87b8b54`). This will not match forks that changed the bytecode.
-- `setPoolFor` can only be called once per project+terminalToken pair. After the pool is set, it cannot be changed. Calling again reverts with `JBBuybackHook_PoolAlreadySet`.
-- Tokens received from the swap are burned via `controller.burnTokensOf`, then re-minted (along with any leftover-mint count) via `controller.mintTokensOf` with `useReservedPercent: true`. This ensures the reserved rate applies uniformly regardless of the payment route.
-- If the swap reverts (slippage, insufficient liquidity, etc.), `_swap` returns 0. The `afterPayRecordedWith` then reverts with `JBBuybackHook_SpecifiedSlippageExceeded(0, minimumSwapAmountOut)`.
-- TWAP fallback: when no observations exist (`oldestObservation == 0`), falls back to spot tick and current liquidity rather than reverting.
-- The sigmoid slippage formula (`JBSwapLib.getSlippageTolerance`) produces smooth tolerance curves. Small swaps in deep pools get ~2% tolerance; large swaps relative to pool liquidity approach the 88% ceiling.
-- `beforePayRecordedWith` is a `view` function -- it cannot modify state. All swap execution happens in `afterPayRecordedWith`.
-- The hook validates that `msg.sender` is a registered terminal of the project via `DIRECTORY.isTerminalOf(projectId, msg.sender)`.
-- Metadata key `"quote"` encodes `(uint256 amountToSwapWith, uint256 minimumSwapAmountOut)`. If `amountToSwapWith == 0`, the full payment amount is used. If `minimumSwapAmountOut == 0`, a TWAP-based quote is calculated.
-- When the payment currency differs from the ruleset's base currency, the hook queries `PRICES.pricePerUnitOf(...)` for the conversion factor.
-- State vars are public: `poolOf[projectId][terminalToken]`, `projectTokenOf[projectId]`, `twapWindowOf[projectId]` -- NOT prefixed with underscore.
-- `_msgSender()` (ERC-2771) is used instead of `msg.sender` for meta-transaction compatibility in permissioned functions (`setPoolFor`, `setTwapWindowOf`).
-- `hasMintPermissionFor` returns `false` on `JBBuybackHook` but returns `addr == address(hook)` on `JBBuybackHookRegistry`. The registry grants mint permission to whichever hook is active for the project.
+- **V4, not V3**: This version uses Uniswap V4 (`IPoolManager`, `PoolKey`, `unlock`/`unlockCallback`). There is no `IUniswapV3Pool`, no `uniswapV3SwapCallback`, no create2 pool address derivation, and no factory. Pools are identified by their `PoolKey` and must be initialized in the V4 PoolManager before calling `setPoolFor`.
+- **Pool immutability**: `setPoolFor` can only be called once per project+terminalToken pair. After the pool key is stored, calling again reverts with `JBBuybackHook_PoolAlreadySet`. This is intentional to prevent swap routing manipulation.
+- **PoolKey validation**: `setPoolFor` validates that the PoolKey's `currency0`/`currency1` match the project token and normalized terminal token. It also checks that the pool is initialized (sqrtPriceX96 != 0).
+- **Burn-and-remint**: Tokens received from the swap are burned via `controller.burnTokensOf`, then re-minted (along with any leftover-mint count) via `controller.mintTokensOf` with `useReservedPercent: true`. This ensures the reserved rate applies uniformly regardless of the payment route.
+- **Swap failure fallback**: If the V4 `POOL_MANAGER.unlock()` call reverts (slippage, insufficient liquidity, etc.), `_swap` catches it with try-catch and returns `(0, true)`. The `swapFailed` flag bypasses the slippage check, allowing the payment to fall through to the mint path. Any WETH wrapped for the swap is unwrapped back to ETH so leftover accounting remains correct.
+- **TWAP oracle fallback**: When the oracle hook is absent or `observe()` reverts, `JBSwapLib.getQuoteFromOracle` falls back to spot price from `poolManager.getSlot0()` and current liquidity from `poolManager.getLiquidity()`.
+- **Zero liquidity protection**: If the oracle/spot returns zero liquidity (`harmonicMeanLiquidity == 0`), `_getQuote` returns 0, which ensures the hook falls back to minting rather than attempting a swap in an empty pool.
+- **Sigmoid slippage ceiling**: If `getSlippageTolerance` returns `>= TWAP_SLIPPAGE_DENOMINATOR` (10,000 bps = 100%), `_getQuote` returns 0 to trigger mint fallback.
+- **Quote floor**: `beforePayRecordedWith` uses the **higher** of the payer's supplied `minimumSwapAmountOut` and the TWAP-derived minimum. A stale or manipulated payer quote cannot produce a worse deal than the oracle suggests.
+- **sqrtPriceLimitX96 protection**: The `unlockCallback` computes a `sqrtPriceLimitX96` from `amountIn` and `minimumSwapAmountOut`. The V4 swap stops early if the price moves beyond this limit, providing on-chain MEV protection.
+- **`beforePayRecordedWith` is a `view` function**: It cannot modify state. All swap execution happens in `afterPayRecordedWith`.
+- **Terminal validation**: `afterPayRecordedWith` validates that `msg.sender` is a registered terminal of the project via `DIRECTORY.isTerminalOf(projectId, IJBTerminal(msg.sender))`.
+- **Native token handling**: When the terminal token is `JBConstants.NATIVE_TOKEN`, the hook normalizes to WETH for storage and pool lookups. For V4 settlement, if the pool's input currency is `address(0)` (native ETH), it uses `settle{value:}`; otherwise it wraps to WETH first via `WETH.deposit{value:}`.
+- **Metadata key**: `"quote"` encodes `(uint256 amountToSwapWith, uint256 minimumSwapAmountOut)`. If `amountToSwapWith == 0`, the full payment amount is used. If not provided at all, same behavior.
+- **State variable names**: Public: `projectTokenOf[projectId]`, `twapWindowOf[projectId]`. Internal with public getter: `poolKeyOf(projectId, terminalToken)` (backed by `_poolKeyOf`). Internal only: `_poolIsSet[projectId][terminalToken]`.
+- **ERC-2771**: `_msgSender()` (ERC-2771) is used instead of `msg.sender` for meta-transaction compatibility in permissioned functions (`setPoolFor`, `setTwapWindowOf`).
+- **Mint permission**: `hasMintPermissionFor` returns `false` on `JBBuybackHook` but returns `addr == address(hook)` on `JBBuybackHookRegistry`. The registry grants mint permission to whichever hook is active for the project.
+- **Registry locking**: `lockHookFor(projectId, expectedHook)` snapshots the default into `_hookOf[projectId]` if the project hasn't explicitly set one. The `expectedHook` parameter prevents race conditions: if the resolved hook differs from what the caller expects, it reverts with `HookMismatch`. This prevents a later `setDefaultHook` from changing the locked project's hook.
+- **Registry setDefaultHook**: `setDefaultHook(address(0))` reverts with `ZeroHook` to prevent DoS when projects without a specific hook try to use the default.
+- **Registry disallowHook**: If `disallowHook` removes the current default, it also clears `defaultHook` to `address(0)`.
+- **Currency conversion**: When the payment currency differs from the ruleset's base currency, the hook queries `PRICES.pricePerUnitOf(...)` for the conversion factor. This is used both in `beforePayRecordedWith` (for comparing mint vs swap) and in `afterPayRecordedWith` (for computing leftover mint tokens).
 
 ## Example Integration
 
 ```solidity
+import {JBBuybackHook} from "@bananapus/buyback-hook-v6/src/JBBuybackHook.sol";
+import {JBBuybackHookRegistry} from "@bananapus/buyback-hook-v6/src/JBBuybackHookRegistry.sol";
+import {IWETH9} from "@bananapus/buyback-hook-v6/src/interfaces/external/IWETH9.sol";
+import {IPoolManager} from "@uniswap/v4-core/src/interfaces/IPoolManager.sol";
+import {PoolKey} from "@uniswap/v4-core/src/types/PoolKey.sol";
+import {Currency} from "@uniswap/v4-core/src/types/Currency.sol";
+import {IHooks} from "@uniswap/v4-core/src/interfaces/IHooks.sol";
+import {JBConstants} from "@bananapus/core-v6/src/libraries/JBConstants.sol";
+
+// Deploy the registry (owner-managed)
+JBBuybackHookRegistry registry = new JBBuybackHookRegistry(
+    permissions,
+    projects,
+    registryOwner,     // address that manages the hook allowlist
+    trustedForwarder
+);
+
 // Deploy the buyback hook
 JBBuybackHook hook = new JBBuybackHook(
     directory,
@@ -98,23 +197,35 @@ JBBuybackHook hook = new JBBuybackHook(
     prices,
     projects,
     tokens,
-    weth,
-    uniswapV3Factory, // factory address for create2 pool derivation
+    IWETH9(weth),
+    IPoolManager(poolManager),
     trustedForwarder
 );
 
-// Configure a pool for project 1 with a 0.3% fee tier and 30-minute TWAP
-IUniswapV3Pool pool = hook.setPoolFor({
+// Register the hook as the default
+registry.setDefaultHook(hook);
+
+// Configure a V4 pool for project 1 with a 30-minute TWAP
+// The pool must already be initialized in the V4 PoolManager.
+address projectToken = address(tokens.tokenOf(1));
+
+hook.setPoolFor({
     projectId: 1,
-    fee: 3000,        // 0.3%
+    poolKey: PoolKey({
+        currency0: Currency.wrap(projectToken < weth ? projectToken : weth),
+        currency1: Currency.wrap(projectToken < weth ? weth : projectToken),
+        fee: 3000,          // 0.3% in V4 fee units (hundredths of a bip)
+        tickSpacing: 60,
+        hooks: IHooks(address(0))  // or an oracle hook address
+    }),
     twapWindow: 30 minutes,
-    terminalToken: address(weth) // or JBConstants.NATIVE_TOKEN
+    terminalToken: JBConstants.NATIVE_TOKEN  // or address(weth)
 });
 
-// Set the hook as the project's data hook in the ruleset config:
+// Set the registry as the project's data hook in the ruleset config:
 // rulesetConfig.metadata.useDataHookForPay = true;
-// rulesetConfig.metadata.dataHook = address(hook);
+// rulesetConfig.metadata.dataHook = address(registry);
 
-// Now when someone pays project 1, the hook automatically
-// compares mint vs swap and takes the better route.
+// Now when someone pays project 1, the registry delegates to the hook,
+// which compares mint vs swap and takes the better route.
 ```

package/foundry.lock

@@ -0,0 +1,11 @@
+{
+  "lib/forge-std": {
+    "rev": "2b59872eee0b8088ddcade39fe8c041e17bb79c0"
+  },
+  "lib/sphinx": {
+    "branch": {
+      "name": "v0.23.0",
+      "rev": "5fb24a825f46bd6ae0b5359fe0da1d2346126b09"
+    }
+  }
+}

package/foundry.toml

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bananapus/buyback-hook-v6",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -18,14 +18,12 @@
     "artifacts": "source ./.env && npx sphinx artifacts --org-id 'ea165b21-7cdc-4d7b-be59-ecdd4c26bee4' --project-name 'nana-buyback-hook-v6'"
   },
   "dependencies": {
-    "@bananapus/core-v6": "^0.0.5",
-    "@bananapus/permission-ids-v6": "^0.0.3",
-    "@exhausted-pigeon/uniswap-v3-forge-quoter": "^1.0.2",
+    "@bananapus/core-v6": "^0.0.9",
+    "@bananapus/permission-ids-v6": "^0.0.4",
     "@openzeppelin/contracts": "^5.2.0",
-    "@uniswap/v3-core": "github:Uniswap/v3-core#0.8",
-    "@uniswap/v3-periphery": "github:Uniswap/v3-periphery#0.8"
+    "@uniswap/v4-core": "^1.0.2"
   },
   "devDependencies": {
-    "@sphinx-labs/plugins": "^0.33.1"
+    "@sphinx-labs/plugins": "^0.33.2"
   }
 }