Constrained visual engineering for Uniswap v4 hooks.

Abstract

Uniswap v4 hooks make pool behavior programmable at defined lifecycle boundaries. That flexibility introduces a demanding engineering surface: callback permissions are encoded in the deployed address, accounting must respect PoolManager semantics, external calls create adversarial risk, and seemingly simple product language can conceal technically invalid assumptions.

hooked on eth. is an engineering studio built around those constraints. Users express intent in natural language or through a node graph. The system lowers that intent into a strict JSON domain-specific language, validates the graph and protocol capabilities, generates Solidity deterministically, produces isolated Foundry evidence, simulates explicit scenarios, mines a permission-compatible CREATE2 address, and prepares a transaction that only the connected wallet can sign.

1. The problem

Hook development spans protocol reasoning, Solidity engineering, adversarial review, deployment infrastructure, and user-facing configuration. A visual editor that merely emits plausible code does not solve this problem. It can instead hide unsupported accounting, overbroad permissions, fabricated data sources, or a deployment address whose permission bits are wrong.

• Callback behavior and hook-address permissions must agree.
• Rolling volume and volatility require an explicit data source; PoolManager does not expose a free 24-hour metric.
• Dynamic LP fees remain LP revenue. Treasury revenue requires a separately modeled and disclosed accounting mechanism.
• Compilation success is necessary but insufficient: tests, findings, gas, simulation assumptions, and deployed runtime evidence matter.
• Financial actions must remain wallet-controlled and explicitly reviewed.

2. Design principles

3. System architecture

The core lowering pipeline is:

1. Natural-language intent
2. Schema-constrained AI proposal
3. Validated Hook DSL
4. Visual workflow and graph validation
5. Contract intermediate plan
6. Deterministic Solidity and tests
7. Isolated Foundry compilation and automated checks
8. Deterministic scenario simulation
9. Permission derivation and CREATE2 salt mining
10. Explicit wallet review and deployment
11. Receipt, event, and runtime reconciliation

The web application manages intent, editing, evidence display, sessions, and wallet requests. PostgreSQL stores projects, immutable versions, evidence, simulations, and deployments. Redis and BullMQ coordinate bounded jobs. A separate worker runs generated projects in restricted containers. Ethereum RPC and explorer services are optional external dependencies that cannot fabricate success when unavailable.

4. Hook DSL

The Hook DSL is a versioned JSON contract between AI, editor, validator, generator, simulator, and persistence. Zod schemas validate both client and server inputs. Node definitions live in a registry with configuration schemas, connection rules, generator handlers, simulation handlers, and validation rules.

{
  "name": "Volume Guard",
  "version": 1,
  "callbacks": ["beforeSwap"],
  "nodes": [
    { "id": "trigger", "type": "trigger", "subtype": "beforeSwap" },
    { "id": "size", "type": "condition", "subtype": "swapSizeThreshold",
      "config": { "amount": "10", "unit": "ETH" } },
    { "id": "reject", "type": "action", "subtype": "rejectSwap" }
  ],
  "edges": [
    { "source": "trigger", "target": "size" },
    { "source": "size", "target": "reject" }
  ]
}

Object shape is closed where financial or protocol behavior is involved. AI modifications produce explicit patches and a change preview; they never mutate a workflow silently. Material changes create versionable state, while deployed versions are never overwritten.

5. Uniswap v4 model

Callbacks and permissions

PoolManager calls a hook only at lifecycle points encoded by the low-order bits of the hook address. hooked on eth. derives the least permissions required by reachable graph behavior and generates the corresponding Hooks.Permissions value. Return delta permissions require their parent callback and are rejected when no supported accounting path exists.

Fees and treasury accounting

A dynamic LP fee changes the pool fee and remains LP revenue. hooked on eth. does not relabel it as treasury income. The supported treasury architecture models a separate hook-owned charge, accounts it through v4-compatible deltas and settlement, accrues balances, and exposes pull-based claims to explicit recipients. Architectures that cannot settle safely are rejected.

Volume state

Rolling volume uses hook-maintained, fixed onchain time buckets. The DSL records metric provenance and window length. External oracle or offchain-only sources must be identified as such; they cannot masquerade as native PoolManager state.

6. Deterministic contract generation

Generator modules map supported nodes into imports, constants, storage, permission declarations, callback branches, accounting, errors, events, tests, and deployment scripts. Identical validated inputs and pinned dependency versions produce identical source and creation bytecode.

A generated standalone Foundry project includes source, baseline tests, deployment script, dependency manifest, compiler settings, README, and project manifest. It is intended to compile outside the hosted platform and remain reviewable without an AI provider.

7. Build evidence

The contract worker accepts validated DSL—not arbitrary shell commands or user-submitted Solidity—and materializes a temporary project. A network-disabled container runs pinned Foundry builds, deterministic tests, gas reporting, source checks, and Slither under CPU, memory, process, filesystem, output, and timeout limits.

• Creation and runtime bytecode hashes
• Compiler version, settings, source hash, and contract size
• Named test outcomes and measured gas evidence
• Structured findings from Critical through Informational
• Compiler-declared immutable ranges for runtime verification

8. Simulation

Simulation is scenario-driven and deterministic. Users specify swaps, sizes, liquidity, price path, duration, volatility, and other supported inputs. The engine executes conditions in callback order and records resulting fees, hook charges, rejections, state transitions, token movements, and modeled gas.

Simulation does not predict market behavior or guarantee future economics. Historical replay is available only when a configured provider supplies verifiable data. Until a run exists, hooked on eth. displays no fabricated metrics.

9. Permission-aware deployment

Ethereum mainnet is the public deployment target. Hook addresses encode permissions, so hooked on eth. hashes the exact creation bytecode and constructor arguments and mines a CREATE2 salt whose predicted address matches the derived permission bitmap.

The immutable HookAIDeployerV1 contract at 0xF0f6…3a18 deploys the reviewed init code atomically with CREATE2 and forwards the disclosed service fee. It has no owner, upgrade path, fee setter, withdrawal function, or arbitrary-call surface. Its fee and recipient are fixed in runtime code.

Before wallet signing, the server verifies the mainnet chain, official v4 PoolManager runtime, hosted deployer runtime, evidence gates, constructor destinations, address vacancy, calldata, fee, and predicted address. After confirmation, hooked on eth. reconciles the transaction sender, value, calldata hash, deployment event, CREATE2 preimage, confirmation depth, and observed runtime. Runtime comparison ignores only compiler-declared immutable byte ranges; all other bytes must match.

10. AI boundary

AI providers implement a replaceable server-side interface for workflow generation, patch proposals, and explanations. Provider keys or subscription credentials never reach the browser. The model receives supported capabilities and minimum workflow context—not private keys, signatures, authentication cookies, or unrelated project data.

Model output is schema-constrained and then independently capability-checked. Unsupported requests return a structured limitation. AI cannot initiate wallet transactions, select hidden recipients, bypass evidence gates, or deploy a contract.

11. Security model

• Signed-message authentication with nonce-bound sessions
• Secure, SameSite session cookies and origin validation
• Client and server schema validation plus rate limits
• No private-key custody or seed-phrase fields
• Isolated, resource-bounded contract workers
• Pinned dependencies and deterministic generator versions
• Explicit high-risk treatment for external contract calls
• Receipt-backed status rather than optimistic deployment claims
• Structured logs that exclude secrets and unnecessary signatures

The primary residual risks include generator defects, compiler or dependency vulnerabilities, incorrect economic assumptions, novel v4 interactions, RPC or explorer faults, malicious external integrations, and user-selected configuration risk. Independent review remains mandatory for production capital.

12. Platform economics

hooked on eth. charges a one-time 0.01 ETH deployment service fee only through its hosted mainnet deployer. The fee is shown before wallet confirmation and is forwarded atomically on successful hook deployment. If deployment reverts, the service fee is not retained, although network gas can still be spent.

Generated hooks contain no ongoing platform royalty. Standalone exports can be reviewed and deployed independently outside the hosted path. The official contract address below is published for identity and discovery; this paper makes no claim about token utility, governance rights, yield, or financial value.

13. Status and roadmap

Roadmap items are architectural direction, not delivery promises. The interface must continue labeling unavailable capabilities as unavailable rather than implying they are live.

14. Risks and limitations

hooked on eth. is developer infrastructure for high-risk smart-contract work. A valid workflow can still implement harmful economics. A passing build and automated checks cannot establish economic safety, composability with every router, resistance to every adversarial strategy, or suitability for unaudited production funds.

The MVP supports a deliberately constrained node set. Wallet allowlists remain design-only until authenticated routerhookData is available. Arbitrary custom Solidity is not accepted in the primary AI workflow. External contract calls require explicit targets and remain higher risk. Unsupported return-delta or settlement architectures fail closed.

15. Conclusion

hooked on eth. treats visual development as a protocol-engineering interface, not a shortcut around engineering. Its central claim is architectural: natural language can help builders express and inspect intent, while closed schemas, deterministic lowering, isolated evidence, permission-aware deployment, and wallet authority preserve a reviewable path to Ethereum.

References

1. Uniswap v4 documentation
2. Uniswap v4-core
3. Uniswap v4-periphery
4. EIP-2470 Singleton Factory
5. hooked on eth. product documentation