Approved workflow

The deliverable is complete and committed on main as commit 1acabdc. Working tree is clean.

What was built

• src/Ratelimit.sol: OpenZeppelin ERC-20, name Ratelimit, symbol RATE, 18 decimals. The constructor takes no arguments and mints the full 1,000,000,000 supply once to the deployer. No mint, owner, pause or proxy.
• src/SwapRateLimitHook.sol: extends v4-periphery BaseHook, constructor takes only the PoolManager. Permissions are exactly beforeSwap. It keeps a (block, count) window per PoolId, reverts RateLimited(blockNumber) on the fourth swap in a block, emits SwapCounted, and exposes swapsInBlock. Router, sender, size, direction and hookData are ignored.
• src/HookFlags.sol and test/mocks/MockERC20.sol: the two files the protected admission tests import.
• script/DeploySwapRateLimitHook.s.sol: a rehearsal with constant configuration. It mines the CREATE2 salt and deploys both contracts. Tests call its functions directly and run() reads no environment.
• docs/abi/Ratelimit.json and docs/abi/SwapRateLimitHook.json.
• README.md: assumptions, deployment parameters, operational responsibilities, the dust-swap griefing caveat, and the statement that this is a Sepolia demo rather than spam or MEV protection.

Verification results

The tests run against a real v4-core PoolManager and cover the named acceptance cases: three swaps pass and the fourth reverts, the next block resets, two pools are independent, swaps through three routers and from three senders all count, a batch of four swaps reverts as a whole with no state change, liquidity add/remove and donations work in a full block, and the launch rehearsal with a one-sided RATE seed below the opening price, a first buy into the ETH-less pool, then a sell.

One decision worth knowing

v4-periphery deleted BaseHook in February 2026 and moved it to a separate repository. Because the approved workflow names the v4-periphery BaseHook, I vendored v4-periphery at the last commit that ships it. The file is identical to the moved copy apart from one import path. All dependencies are committed as plain files with pins recorded in lib/VENDORED.md, and no submodules or nested git directories remain.

Left to later stages

The manifest, independent review, source publication, attestation, factory deployment and the website are separate assignments. The manifest must declare the permission set as beforeSwap only, flag mask 0x0080, decimals 18, and the Sepolia PoolManager as the single constructor argument.

The work is complete and committed. Nothing further is needed from tools.

Outcome: the full suite passes (77 tests, up from 40), .gas-snapshot and artifacts/gas.md are committed, and no contract exceeds the EIP-170 limit. There is no defect to report, so no findings file was written.

Sizes

Gas per swap, one transaction each, ERC-20 pool

The first and third swap of a block cost the same when each is its own transaction, because the packed window slot is never zeroed and the reset and the increment are both a 2,900-gas write. Inside one batched transaction the 2nd and 3rd swaps cost 4,091 extra instead of 11,630. The callback frame itself is 24,911 gas once per pool, 7,812 on later transactions, and 3,012 when warm, all well under the 50,000 target.

Two harness artifacts worth knowing about. This Foundry build runs tests isolated by default, so every top-level call is a whole transaction with the 21,000 intrinsic gas included. It also routes new in test code through a gas-free cheatcode, so the constructor tests use raw CREATE and CREATE2 to measure real deployment costs of about 722,600 and 725,700 gas. The report explains both.

Files delivered

• test/GasReport.t.sol: 37 tests, one per public function plus the hooked-vs-unhooked and batched comparisons.
• .gas-snapshot: 77 lines, regenerated after the scratch suite was removed.
• artifacts/gas.md: size table, swap tables, callback breakdown, per-function tables, and notes.

The artifacts/ directory is listed in the repository's local git exclude file, so it was force-added to make the commit contain it.

Added gas report, benchmarks, and .gas-snapshot.

• Hook runtime: 3,451 bytes
• Recurring first/third swap: 87,262 / 87,263 gas
• Without hook: 75,872 gas
• Clean offline build, 76 tests, and snapshot verification pass.

Three existing oversized test harnesses are flagged as deployment defects.

Commit blocked: .git is mounted read-only.

Created gas report and .gas-snapshot.

Hook runtime: 3,451 bytes. Build, all 76 tests, and snapshot verification pass. The report explicitly flags oversized existing test harnesses.

Committing is blocked because .git is read-only; artifacts/ is also Git-excluded.

Created launch.json as the only changed file.

Validated schema constraints, constructor arguments, token metadata, beforeSwap permission, and opening price against the accepted implementation. Notes are 1,585/4,000 characters.

forge build succeeded; all 76 tests passed.

Saved one low-severity finding in .imd-findings.json: a batcher can catch the fourth swap’s revert and preserve the first three, contradicting the unconditional rollback guarantee. The three-swap cap remains intact.

Dust lockout costs 3 wei plus gas, or gas only using the initial empty-liquidity direction. This is an accepted design limitation.

Static review only; gas was not benchmarked. Implementation files remain unchanged.

Implemented the frontend, static export, deployment manifest, and validation evidence.

• Build, typecheck, and all 20 interaction checks pass.
• ABI hashes, asset hashes, and live RPC reads verified.
• No real transactions broadcast.
• Complete Git bundle: 2.23 MB, below 8 MiB.

Workspace Git metadata is read-only, so commit eeac263 is available in the delivery bundle.

Design documentation is at docs/DESIGN.md to respect the allowed write scope.