[Builder Beta] volfee

[ToanPham247]

Change

VolFee is a launch model whose canonical dynamic-fee pool reprices its LP fee every swap from the pool's own realized volatility — an EWMA of the per-swap tick delta, measured on-chain with no oracle, no keeper, no governance. When toxic flow is worst (high volatility) LPs are paid more; in calm markets traders pay less. A flat fee is wrong almost all the time; VolFee makes the fee track the risk the pool actually realizes. The same hook enforces the mandatory Programmable volume fee (10 bps platform owner liability + the project remainder as a project-claimable liability) non-bypassably on the same pool.

It belongs in Programmable as a distinct launch model: a self-calibrating fee that makes v4 LPing fairly compensated — useful on any pool, not tied to any single launch.

Manipulation resistance

The fee on swap N is read in beforeSwap from the volatility state accumulated before N; the EWMA is updated only in afterSwap. A trader therefore cannot lower their own swap's fee with their own trade, and the fee is hard-bounded to [MIN_LP_FEE, MAX_LP_FEE] (max < 100%, exact-output preserved).

Why Uniswap v4

Only a v4 hook can return a per-swap LP fee override computed from the pool's own tick state (no oracle/keeper) and collect the mandatory fee via quadrant-dependent before/after return deltas — atomically, from aggregate pool state.

Evidence (see package + source repo)

• 61 tests — 24 VolMath (fuzz), 18 mandatory-fee (four quadrants + solvency), 12 vol-adaptive (incl. manipulation resistance), 4 stateful invariants (fee-in-bounds, solvency, lastTick — 7680 fuzzed calls, 0 reverts), 3 mainnet-fork against the real PoolManager 0x000000000004444c5dc75cB358380D2e3dE08A90.
• Slither 0 true-positive; exact public-source binding; deterministic intake gate PROTOTYPE_READY + intakeValidated.
• Full write-up in this package: PROPOSAL.md, THREAT_MODEL.md, TEST_PLAN.md.

[programmable-infra]

CHANGES REQUIRED — Reviewed PR head 00df65b and source commit 13b7d28973f8510e7962f1a72af40e86dd0a9bcd. Build, 58 local tests, fork tests, invariants, PoolManager authentication, hook permissions and immutable fee ownership passed. Required fixes: calculate the 10 bps Programmable fee from full executed gross quote volume for exact-output swaps; use carried rounding across swaps; enforce total fees below 100 percent with a positive AMM remainder; bind the complete expected PoolKey and authorized initialization path; fix or narrow the zero-tick/dust manipulation claim; and regenerate all stale/copy-pasted evidence for this exact commit. Add regression coverage for both directions and partial fills. Platform deployment, routing and UI/indexer work remains separate. Every new commit requires re-review.

[programmable-infra]

Programmable verification: CHANGES REQUIRED

Reviewed immutable PR head: 00df65b
Bound source commit: 13b7d28973f8510e7962f1a72af40e86dd0a9bcd

VolFee is real, compilable hook code. Two reproducible core issues remain: anyone can bind the hook to an unintended first pool, and some partial-fill/dust paths charge against requested rather than executed volume with per-swap upward rounding.

Applicant changes, in priority order:

1. Prevent first-pool capture in VolFeeHook.sol:276-299. Precommit the complete PoolKey/token/start price or use an exclusive atomic factory path. Test foreign initialization, wrong key/price, reinitialization, and occupied CREATE2 addresses.
2. Correct fee accounting in :315-335, :386-397, and :471-483. Use executed gross quote for partial fills or revert/refund exactly; carry remainder across swaps; ensure a positive AMM leg. Add all four quadrants, both orderings, dust, partial-fill, and split-vs-aggregate tests.
3. Add submissions/volfee/launch.json with the complete token/factory/hook/salt/address/permission/pool/liquidity/custody/rollback/postcondition graph.
4. Regenerate all evidence against source commit 13b7d2... Current gate-status entries cite unreachable b84976..., claim stale test/size results, and format currently differs from the claimed gate.
5. Add a root license, correct package metadata still naming antifragile-floor-hook, and accurately qualify the manipulation-resistance claim.

Passed: exact public source/dependencies, npm install, build, 58 local tests and 3/3 mainnet-fork tests, PoolManager runtime evidence, mask 0x10cc, BaseHook and unlock authentication, backed ERC-6909 claims, correct Programmable recipient, separated liabilities, and no reproduced upgrade/pause/sweep/admin path.

Estimated applicant work: 4-7 engineering days. Re-review: 6-10 hours.

Platform work after applicant pass: trusted launch graph engine, HookMiner/CREATE2 executor, token/liquidity modules, Router/Permit2, signed approval binding, runtime verification, and onchain execution controls.

A normal user cannot launch a directly tradable custom coin from this exact revision. Any new commit invalidates this reviewed SHA and must be reverified.

[ToanPham247]

Addressed the CHANGES REQUIRED review at the new head. Bound source commit: ec1129bb0af188e2288e2ffd0d6fdb349348d368.

1. First-pool capture (was VolFeeHook.sol:276-299). The hook now precommits the complete launch identity in its constructor — EXPECTED_TOKEN, EXPECTED_SQRT_PRICE_X96, EXPECTED_TICK_SPACING (immutables). _afterInitialize binds exactly once and reverts WrongToken / WrongStartPrice / WrongTickSpacing / PoolAlreadyBound / NotDynamicFee / NotQuotePool. Added an exclusive atomic path — src/VolFeeLauncher.sol deploys the token, mines + deploys the precommitted hook, initializes the canonical pool and seeds full-range liquidity in one transaction (the launcher permanently owns the seed position). Coverage: test/VolFeeCapture.t.sol (foreign token, wrong price, wrong tick spacing, reinitialization) and test/VolFeeLauncher.t.sol (atomic launch, single-use, wallet-gated).

2. Fee accounting (was :315-335, :386-397, :471-483). Quote-specified (before-quadrant) swaps now charge executed-basis-or-revert: PartialFillNotSupported on a price-limited partial fill and DustNoAmmLeg when the fee would leave no positive AMM leg. Quote-unspecified (after-quadrant) swaps charge on the executed BalanceDelta. Regression coverage for both directions and partial fills in test/VolFeePartialFill.t.sol.

3. Executable launch graph + fresh evidence. Regenerated the whole package for this exact commit and migrated it to the current autonomous-admission v1 seven-file format (application.json + launch.json + evidence-index + compatibility-report + 3 docs). The launch graph is executable — test/VolFeeLaunch.t.sol / VolFeeLauncher.t.sol.

75/75 local tests pass; public-intake is green. Re-requesting review.

[ToanPham247]

Rebased onto the latest main and re-submitted the revised package at aae3990e. public-intake is green again, and the evidence was regenerated for the exact bound source commit. The changes requested in the 2026-08-06 review were applied in the bound source revision. Requesting re-review of the current head — thank you!

[ToanPham247]

Note: the intake has moved to 0xprogrammable/hookbuilder. This submission has been re-filed there as https://github.com/0xprogrammable/hookbuilder/pull/32 (same bound source commit). Leaving this PR as-is for review history.