v4-hook-generator

What this skill does

# v4 Hook Generator

Generate Uniswap v4 hook contracts via the OpenZeppelin Contracts Wizard MCP tool. This skill
guides you through selecting the right hook type, configuring permissions and utilities, assembling
the canonical MCP JSON, and invoking the MCP tool to produce ready-to-compile Solidity code.

> **Security companion**: Generated hook code touches fund-handling contracts. Always apply the
> `v4-security-foundations` skill immediately after generation to audit permissions, delta
> accounting, and access control before deploying to any network.

## When to Use This Skill

Use this skill when you need to:

- Scaffold a new Uniswap v4 hook contract from scratch
- Select the right base hook type for a specific use case (fees, MEV protection, oracles, etc.)
- Configure hook permissions, utility libraries, shares, and access control
- Produce the canonical MCP tool call JSON to invoke the OpenZeppelin Contracts Wizard
- Understand trade-offs between hook configuration options before committing to an implementation

**Prerequisite / companion skill**: `v4-security-foundations` — run it before writing custom logic
and again before deployment. Hook misconfiguration can drain user funds.

## Hook Type Decision Table

Choose the base hook type that matches your primary goal. If your hook has multiple goals, choose
the type that covers the most critical concern and layer additional logic on top.

| Goal                 | Use Hook                   |
| -------------------- | -------------------------- |
| Custom swap logic    | `BaseHook`                 |
| Async/delayed swaps  | `BaseAsyncSwap`            |
| Hook-owned liquidity | `BaseCustomAccounting`     |
| Custom curve         | `BaseCustomCurve`          |
| Dynamic LP fees      | `BaseDynamicFee`           |
| Dynamic swap fees    | `BaseOverrideFee`          |
| Post-swap fees       | `BaseDynamicAfterFee`      |
| Fixed hook fees      | `BaseHookFee`              |
| MEV protection       | `AntiSandwichHook`         |
| JIT protection       | `LiquidityPenaltyHook`     |
| Limit orders         | `LimitOrderHook`           |
| Yield on idle        | `ReHypothecationHook`      |
| Oracle               | `BaseOracleHook`           |
| V3-compatible oracle | `OracleHookWithV3Adapters` |

**Selection tips**:

- `BaseHook` is the general-purpose starting point — choose a specialized type only when the
  built-in logic provides concrete value.
- `BaseCustomCurve` replaces the entire AMM math; only use it if you are implementing a novel
  pricing algorithm.
- `AntiSandwichHook` and `LiquidityPenaltyHook` both address MEV but target different actors
  (traders vs. JIT LPs). Clarify which attack vector you are mitigating.
- `OracleHookWithV3Adapters` is appropriate when downstream integrations expect a Uniswap v3
  `IUniswapV3Pool`-compatible oracle interface.

## Minimal Decision Checklist

Before calling the MCP tool, confirm all six decisions:

1. **Hook type** — chosen from the decision table above
2. **Permissions to enable** — only the callbacks your logic actually uses (`beforeSwap`, `afterSwap`, etc.)
3. **Utility libraries** — `currencySettler`, `safeCast`, `transientStorage` as needed
4. **Shares** — `false`, `ERC20`, `ERC6909`, or `ERC1155`
5. **Access control** — `ownable`, `roles`, or `managed`
6. **Hook inputs** — `blockNumberOffset`, `maxAbsTickDelta` (only for hook types that use them)

## Permission Configuration

All 14 permission flags with guidance on when to enable each. Start with all flags `false` and
enable only what your hook logic requires. Every enabled permission increases the hook's attack
surface and requires a specific bit to be set in the hook's deployed address (see address encoding
note below).

| Permission Flag                   | Enable When                                                                                                     | Risk     |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------- | -------- |
| `beforeInitialize`                | You need to validate or restrict pool creation params                                                           | LOW      |
| `afterInitialize`                 | You need to set up state after a pool is created                                                                | LOW      |
| `beforeAddLiquidity`              | You need to gate or transform LP deposits                                                                       | MEDIUM   |
| `afterAddLiquidity`               | You track LP positions or distribute rewards                                                                    | LOW      |
| `beforeRemoveLiquidity`           | You need lock-up periods or fee-on-exit logic                                                                   | HIGH     |
| `afterRemoveLiquidity`            | You track position removals for accounting                                                                      | LOW      |
| `beforeSwap`                      | You modify swap behavior, apply dynamic fees, or block                                                          | HIGH     |
| `afterSwap`                       | You observe final swap state for oracles or accounting                                                          | MEDIUM   |
| `beforeDonate`                    | You restrict who may donate to the pool                                                                         | LOW      |
| `afterDonate`                     | You track donation events                                                                                       | LOW      |
| `beforeSwapReturnDelta`           | You implement custom AMM curves or JIT liquidity (CRITICAL: NoOp attack vector — see `v4-security-foundations`) | CRITICAL |
| `afterSwapReturnDelta`            | You extract a hook fee from swap output                                                                         | HIGH     |
| `afterAddLiquidityReturnDelta`    | You adjust LP token amounts on deposit                                                                          | HIGH     |
| `afterRemoveLiquidityReturnDelta` | You adjust withdrawal amounts                                                                                   | HIGH     |

**Address encoding note**: Permissions are encoded as bits in the hook contract's deployed address.
The address must have the correct bits set at deployment time or the PoolManager will revert. Use
`HookMiner` (from `v4-periphery`) to mine a salt that produces an address with the correct bit
pattern. Never change permissions after deployment — the address is immutable.

## Utility Library Selection

Three optional utility libraries can be included in the generated hook. Include only what your
hook logic uses.

| Library            | Include When                                                                                                                                                |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `currencySettler`  | Your hook moves tokens between itself and the PoolManager (e.g., custom accounting, fee collection)                                                         |
| `safeCast`         | Your hook performs arithmetic that could overflow when casting between integer types                                                                        |
| `transientStorage` | Your hook needs to pass data between callbacks within a single transaction without persisting to storage (requires EVM Cancun or later, Solidity >= 0.8.24) |

**Guidance**:

- `currencySettler` is almost always needed when `beforeSwapReturnDelta`,
  `afterSwapReturnDelta`, `afterAddLiquidityReturnDelta`, or `afterRemoveLiquidityReturnDelta`
  are enabled — it provides `settle