Build from protocol constraints, not generated prose.
A practical guide to HookAI’s supported Uniswap v4 workflow, evidence, accounting, and deployment boundaries.
The model proposes intent. The generator owns source.
Every workflow is validated against a closed schema before graph or generator use.
{
"version": 1,
"callbacks": ["beforeSwap", "afterSwap"],
"nodes": [
{ "type": "condition", "subtype": "volumeThreshold",
"config": { "source": { "type": "hookState" },
"windowSeconds": 86400, "value": 1000000 } }
]
}Getting Started
Open Studio in demo mode, describe a supported hook, inspect the proposed graph, and edit node settings. A wallet is optional for local design and required for account-owned versioning, build jobs, and deployment.
What is a v4 Hook?
A hook is a contract PoolManager calls at permissioned lifecycle points. The same PoolManager owns pool state for every v4 pool. A hook must implement its callbacks correctly and its deployed address must encode exactly the permissions it declares.
Hook Lifecycle and Callbacks
v4 supports before/after initialize, add liquidity, remove liquidity, swap, and donate callbacks. HookAI currently generates the beforeSwap/afterSwap architecture needed by the MVP nodes; unsupported callback graphs fail closed.
Permissions
HookAI derives the least required bitmap from reachable nodes. Callback bits occupy the lowest 14 bits of the hook address. Return-delta permissions are enabled only for workflows that use supported custom accounting.
Visual Nodes
Registry definitions own configuration schemas, inputs, outputs, generator behavior, simulation behavior, and validation rules. MVP generation supports Before Swap, Volume Threshold, specified Swap Size Threshold, Dynamic Fee, Treasury Split, and Reject Swap. Wallet Allowlist remains design-only until authenticated router hookData exists.
AI Generation and Modification
AI proposes schema-constrained workflow JSON or explicit patches. Zod validation and the capability registry reject unsupported output before it reaches the editor. Changes are previewed and require acceptance; the AI never signs or deploys.
Simulation
The deterministic scenario engine evaluates callback conditions in swap order and records successful swaps into rolling hook state afterward. It separates modeled LP fees from hook-owned charges and discloses price-path and liquidity limitations. No metrics appear until a run completes.
Compilation, Testing, and Automated Checks
Authenticated projects can queue a pinned Foundry build in a network-disabled container. The worker compiles generated source, runs deterministic tests, reports measured evidence, performs source rules and Slither analysis, and stores structured results. Automated checks do not replace an audit.
Deploying
The public deployment target is Ethereum mainnet. Deployment requires successful compilation, tests, completed automated checks, an explicit quote currency and project recipient, verified mainnet protocol runtimes, typed review acceptance, and a wallet-signed transaction. HookAI never has custody of keys or signatures.
CREATE2 Hook Addresses
The miner hashes the exact creation bytecode plus constructor arguments and searches salts against the verified EIP-2470 factory. A result is accepted only when the predicted address low bits exactly equal the workflow permission mask and the address is unused on Ethereum mainnet.
Security Model
Server-side validation, signed-message sessions, origin checks, rate limits, secure cookies, constrained workers, no wallet custody, and explicit transaction review form the platform boundary. Findings use Critical through Informational severity and never produce an ‘audited’ claim.
Exporting and Versioning
HookAI JSON includes immutable workflow versions and evidence hashes. The standalone Foundry ZIP contains source, tests, deploy script, pinned dependency manifest, foundry.toml, and README so it can be reviewed and compiled outside HookAI.
FAQ
Does HookAI audit generated hooks?
No. It produces automated evidence and findings that should support, not replace, independent review.
Can AI deploy or change a destination?
No. AI output is a proposal. Destination changes are shown in a patch preview and deployment requires a wallet-side confirmation.
Are dynamic LP fees treasury revenue?
No. Dynamic LP fees remain LP revenue. The current treasury architecture uses a separately disclosed hook-owned charge and pull claims.
Where does rolling 24-hour volume come from?
The supported workflow maintains fixed onchain time buckets in hook storage. It does not assume PoolManager exposes a free 24-hour volume variable.