Deploy Uni Hook

Steps

1. Parse ${var}. Extract the arm: flag, the optional template:, the optional chain:, and the free-text brief. Empty brief → exit DEPLOY_HOOK_EMPTY with the grammar.

2. Resolve the chain. The chain name resolves in chains.tsv (default base-sepolia); hook-deploy.sh maps it to the official PoolManager + RPC, so you pass the NAME, not the address. Run ./hook-deploy.sh chains to see the list, or read chains.tsv. If the name is not in the registry, exit DEPLOY_HOOK_BAD_CHAIN. Look up the row's testnet column: if it is false (mainnet), enforce the double opt-in — require BOTH arm: and an explicit chain: in ${var}, else exit DEPLOY_HOOK_BAD_CHAIN. Every Uniswap v4 chain is supported (Base, Ethereum, Unichain, Arbitrum, Optimism, Polygon, BNB, Avalanche, Robinhood, Worldchain, Ink, Soneium, Celo, X Layer + their testnets).

3. Confirm the staged toolchain + project. The workflow pre-stages everything before this run (scripts/stage-deploy-uni-hook.sh): Foundry on $PATH, a pre-built v4 project at $HOOKBUILD_DIR (default $HOME/hookbuild) holding all three templates + MockERC20.sol + DeployHook.s.sol + the v4 libraries, and ./hook-deploy.sh copied to the repo root. Do not install Foundry or clone the libs in-run — the sandbox blocks that. Check command -v forge and that $HOOKBUILD_DIR exists; if either is missing, degrade to DEPLOY_HOOK_NO_TOOLCHAIN (emit the generated source + plan).

4. Build the hook (brief-driven).

   • Template mode (dynamic / noop / skim): in $HOOKBUILD_DIR/src/<Hook>.sol, edit ONLY the region between // --- AEON:LOGIC START --- and // --- AEON:LOGIC END ---. Keep the callback signatures and flag set unchanged. If the default already fits the brief, leave it.
   • Freeform mode (anything else): write the whole hook into $HOOKBUILD_DIR/src/Hook.sol, replacing the // --- AEON:BODY ... --- region. Rules: keep the contract as contract Hook is AeonFee and the constructor as constructor(IPoolManager _pm) AeonFee(_pm). Do NOT implement afterSwap, poolManager, onlyPoolManager, or NotPoolManager - they come from AeonFee and the mandatory 10 bps fee is taken automatically (the audit rejects a Hook that is not is AeonFee, and rejects a redeclared afterSwap). For post-swap logic override _afterSwapExtra (return 0, or an additional delta the hook itself takes). Implement any OTHER v4 callbacks the prompt needs, each with the EXACT IHooks signature, onlyPoolManager, and the right selector return. Do NOT hand-set flags - they are auto-derived from your callbacks (plus the always-on AeonFee afterSwap/afterSwapReturnsDelta bits). If another callback returns a non-zero delta, set HOOK_RETURNS_DELTA in $HOOKBUILD_DIR/hook.env; for a fee-override hook set HOOK_POOL_FEE=dynamic there. Follow Labs routing and Fleet audit rules: empty hookData must succeed; a game must not revert a vanilla exact-in swap; an extra take() (in _afterSwapExtra) must charge magnitude (exact-in and exact-out) and never custody; a price/balance/skew gate must add the afterInitialize callback and anchor to the pool's own start price (Gates rule 6), never an implicit 1.0.
     • Also write the behavioral test. In $HOOKBUILD_DIR/test/Hook.t.sol, replace the // --- AEON:ASSERT ... --- region with test_* functions that assert the hook's SPECIFIC intended behavior — not just "does not revert". For every rule in the brief write at least one positive and one negative case: a swap the hook must REJECT as _expectSwapRevert(zeroForOne, amount, Hook.SomeError.selector) (this helper unwraps v4's WrappedError for you — do NOT use bare vm.expectRevert, it won't match the wrapper); a swap it must ALLOW as a plain _swap(...); any getter/accounting as assertEq(hook.someGetter(...), expected). For a gate whose decision depends on price or reserve balance, assert it through _freshPoolAt(<non-1:1 sqrtPriceX96>) (both legs, off parity) - setUp()'s pool is at 1:1, where such a gate always looks correct. Do NOT edit setUp() or the helpers - only the AEON:ASSERT region. If the brief has no rejectable behavior, still assert the observable state the hook changes.

5. Simulate + audit (always). Pass mode, kind, and chain (chain omitted = base-sepolia):

   ./hook-deploy.sh simulate <kind> <chain>

   For freeform this runs, in order, three gates before any deploy:

   1. Static audit - derives the flags from the callbacks; checks the contract is named Hook, is is AeonFee (mandatory fee) and does not redeclare afterSwap, has ≥1 callback or _afterSwapExtra, every callback carries onlyPoolManager, test/Hook.t.sol has ≥1 test_ function, and scans for dangerous patterns (selfdestruct/delegatecall are hard fails; tx.origin/raw value-call/inline assembly print a warning to review). A failure exits DEPLOY_HOOK_AUDIT_FAILED (never deploy).
   2. Behavioral test — forge test --fork-url <chain> --match-contract HookBehaviorTest runs the agent-written assertions on a fork. A failing OR non-compiling test exits DEPLOY_HOOK_TEST_FAILED (never deploy). This proves the hook does what the prompt asked.
   3. Fork simulation — forge script compiles, mines the salt, deploys in-memory, initializes the pool, adds liquidity, and runs one swap against a fork of the target chain. On a compile error, fix and retry (max 3). On a sim revert, exit DEPLOY_HOOK_SIM_FAILED. Capture the mined hook address, the derived flags, and the Estimated amount required. On mainnet, compare that estimate to the deployer balance (cast balance <addr> --rpc-url <rpc>) and exit DEPLOY_HOOK_UNDERFUNDED if it will not cover it. For a freeform hook, also read the generated Hook.sol and reason about safety before arming: does any callback let a caller steal funds, brick the pool (unconditional revert), or reenter? If unsure, stop at the dry-run and report the concern.

6. Dry-run stop. If ${var} did NOT start with arm:, STOP here. Report: template, mined address (with its flag bits), the receipt routing line (auto-route vs allowlist + reason), the pool key, and the simulation result. Exit DEPLOY_HOOK_DRY_RUN.

7. Arm checks (only if arm:).

   • Confirm HOOK_DEPLOYER_PRIVATE_KEY is set (it is injected via requires:). If not, degrade to the dry-run report and exit DEPLOY_HOOK_NO_KEY.
   • Read memory/state/hook-deploys.json. If the same (chain, template, brief) deployed in the last hour, exit DEPLOY_HOOK_IDEMPOTENT with the prior address.

8. Broadcast.

   ./hook-deploy.sh broadcast <kind> <chain>

   The runner prints a deploy receipt (hook address, decoded flag names, explorer deep-link, tx hashes) and, when ETHERSCAN_API_KEY is set on an Etherscan-family chain, auto-verifies the hook source on the explorer (best-effort — a failed verify never fails a completed deploy). If it printed ALREADY_DEPLOYED, treat the reported address as the result (no new deploy). Read the hook address and the transaction hashes from the receipt or $HOOKBUILD_DIR/broadcast/DeployHook.s.sol/<chainId>/run-latest.json.

9. Verify. With cast, read the pool back through StateView.getSlot0(poolId) on the RPC. Confirm the pool exists and the hook address low bits equal the template's flags. Confirm the swap emitted the hook event.

10. Record the deploy. The deploy already happened on-chain — this is append-only history, not a change to review, so DO NOT open a PR or a branch. Just write the record into the working tree on main; the workflow's post-run commit lands it. Write:

    • memory/state/hook-deploys.json — append this deploy (chain, template, brief, hook address, flags, tx hashes, timestamp, poolId, poolKey).
    • output/hooks/<hook-address>.sol — copy the deployed source from $HOOKBUILD_DIR/src/<Hook>.sol.
    • For freeform, also output/hooks/<hook-address>.t.sol — copy $HOOKBUILD_DIR/test/Hook.t.sol (the behavioral test that gated the deploy).

    Do NOT stage the root ./hook-deploy.sh or ./chains.tsv (runtime copies; both gitignored).

11. Publish to the public hook list (live mainnet deploys only). If this was a real broadcast (not a dry-run) to a mainnet chain the registry supports (ethereum base robinhood monad bnb arbitrum unichain), list the hook on aeonfun/univ4-hooks so it appears on the aeon hook marketplace. Reuse the submit-hook skill's helper - it decodes the flags from the address, formats the entry, regenerates the registry, and opens a PR (issue fallback when there is no push access):

    python3 skills/submit-hook/submit-univ4.py \
      --address "$HOOK_ADDR" --chain "$CHAIN" \
      --name "$NAME" --category "$CATEGORY" --klass "$KLASS" \
      --template "$TEMPLATE" --stage deployed --source aeon --verified \
      --date "$(date -u +%F)" \
      --mechanic "$MECHANIC" --plain "$PLAIN" --rule "$RULE1" --rule "$RULE2"

    Derive name/category/klass/mechanic/plain/rules from the brief exactly as skills/submit-hook/SKILL.md describes. This is best-effort: a submission failure must NEVER fail a completed deploy - log it and continue. Skip entirely on a dry-run, a testnet, or an unsupported chain.

12. Notify + exit. Send a short notification (template, address, explorer link, routing class, dry-run vs live, and the hook-list PR URL when one was opened). Exit DEPLOY_HOOK_OK (or DEPLOY_HOOK_DRY_RUN).

Degrade rules

• No key → dry-run report, DEPLOY_HOOK_NO_KEY. Never fail hard.
• Foundry or the staged project missing (command -v forge fails or $HOOKBUILD_DIR absent) → emit the generated source + plan, DEPLOY_HOOK_NO_TOOLCHAIN. Do not try to install in-run (the sandbox blocks it).
• Bad/missing chain, or mainnet without the double opt-in → DEPLOY_HOOK_BAD_CHAIN.
• Mainnet chain but the instance did not set HOOK_MAINNET_OK=1 (hook-deploy.sh exit 7) → DEPLOY_HOOK_MAINNET_NOT_AUTHORIZED (never broadcast).
• Mainnet balance below the simulation estimate, or the deployer is unfunded (hook-deploy.sh exit 8) → DEPLOY_HOOK_UNDERFUNDED (never broadcast).
• Gas price above MAX_GAS_GWEI (hook-deploy.sh exit 9) → DEPLOY_HOOK_GAS_TOO_HIGH (never broadcast; retry when fees drop).
• Freeform static audit fails (bad name / no callback / missing onlyPoolManager / no test_ / selfdestruct / delegatecall) → DEPLOY_HOOK_AUDIT_FAILED (never deploy).
• Freeform behavioral test fails or does not compile → DEPLOY_HOOK_TEST_FAILED (never deploy).
• Simulation revert → DEPLOY_HOOK_SIM_FAILED (never broadcast after a failed sim).

Notes

• The three templates are pre-validated: each compiles and simulates a full deploy + swap on Base Sepolia. All inherit AeonFee, so all carry the return-delta bits and are allowlist (dynamic = 0x10C4; noop = 0xC4; skim = 0x44).
• Freeform builds an arbitrary hook from the prompt into src/Hook.sol and its behavioral test into test/Hook.t.sol. Flags are auto-derived from the callbacks (never hand-set). Three gates run before any deploy: a static audit (name/callbacks/onlyPoolManager/test-present/dangerous-pattern scan), the agent-written forge test behavioral assertions on a fork, then the fork simulation. The agent also reads the generated source for steal/brick/reentrancy risk before arming. Prefer a matching template when one fits (they are audited); use freeform for novel logic.
• Every deploy — template or freeform — always simulates on the target chain's fork first, so "does it work" is checked before any broadcast.
• Any Uniswap v4 chain works. chains.tsv carries every official v4 deployment (Base, Ethereum, Unichain, Arbitrum, Optimism, Polygon, BNB, Avalanche, Robinhood, Worldchain, Ink, Soneium, Celo, X Layer + the Sepolia testnets), each verified to hold the PoolManager. The same flow runs on all of them — only the PoolManager/RPC differ, resolved by name. The CREATE2 deployer (0x4e59…4956C) is required for the mined address; if a chain lacks it the fork simulation fails closed before any broadcast.
• Mainnet is gas-only. The deploy mints its own MockERC20 tokens to itself (free) and seeds the demo pool with those mock tokens — a mainnet broadcast risks GAS ONLY, never real capital. The deployed pool is a MockA/MockB demo; the reusable hook contract is the real deliverable. The deployer key must be a funded burner holding gas float only (the runner warns above HOOK_MAX_FLOAT_ETH); mainnet also needs the HOOK_MAINNET_OK=1 operator lock. A future version can add the keyless Base MCP send_calls rail so no key sits in the runner.
• Authenticated RPC + receipt + verify. On mainnet the runner prefers an Alchemy endpoint (ALCHEMY_API_KEY + the chain's alchemy slug) over the public RPC, so a lying public node can't fake a clean sim. After a broadcast it prints a receipt (address, decoded flags, explorer link, tx hashes) and, with ETHERSCAN_API_KEY on an Etherscan-family chain, auto-verifies the source (best-effort). All of this is opt-in: with no keys set the skill still runs on public RPCs, unverified.