Build and launch SwapCounterHook, a Uniswap v4 hook that counts swaps per pool, from an empty repository through to a Sepolia deployment.

The contract-level doc block states: "afterSwap returns a zero delta, which is the only delta it is allowed to return with afterSwapReturnDelta off - a non-zero one would make the manager revert."

The second half is false. v4 decides whether to read the hook's delta from the AFTER_SWAP_RETURNS_DELTA flag, and when that flag is off it never reads the returned word at all: Hooks.afterSwap (lib/v4-core/src/libraries/Hooks.sol:299-302) calls callHookWithReturnDelta(..., parseReturn = self.hasPermission(AFTER_SWAP_RETURNS_DELTA_FLAG)), and callHookWithReturnDelta (same file, lines 159-167) does if (!parseReturn) return 0; before it parses anything.

Only the selector and a >=32-byte return are validated. So a non-zero delta with the flag off is discarded, not rejected. The hook's actual behaviour is correct - it returns int128(0), which the delivered tests pin (test_afterSwapReturnsTheSelectorAndAZeroDelta, testFuzz_afterSwapAlwaysReturnsAZeroDelta) - so nothing is wrong on chain today.

What is wrong is the safety argument written next to it. The doc block is explicitly a list of properties that "must stay absent if it is changed", and it tells the next maintainer that the manager is a backstop against returning value from afterSwap. It is not one.

A maintainer who adds a fee by returning a non-zero delta gets no revert, no error, and no fee: the intended charge disappears and the pool's accounting is untouched, which is far harder to notice than the revert the comment promises. This cannot be asserted in a test of this hook - the hook returns zero, and a test that pretends the manager would revert would be asserting a false claim - so it is reported instead.

The doc block states the invariant as "swapCount[id] is monotonically non-decreasing and rises by exactly one per completed swap on the pool id identifies", unqualified. v4 has one exception to that: Hooks.afterSwap (lib/v4-core/src/libraries/Hooks.sol:293) opens with if (msg.sender == address(self)) return (swapDelta, BalanceDeltaLibrary.ZERO_DELTA);, so when the account that called PoolManager.swap is the hook itself, afterSwap is skipped entirely and the swap completes uncounted.

This is NOT a defect in the code as written: SwapCounterHook has no unlockCallback, no call to the manager, and no way to be the caller of swap, so the exception is unreachable and the invariant holds exactly as stated for the deployed contract.

It is reported because the paragraph it appears in is the contract's forward-looking contract with its maintainers - it enumerates what must stay true if the code changes - and the condition that makes the invariant hold (this hook never initiates a swap) is not among the things it lists. Adding any manager-facing call to the hook later would silently undercount, and the doc as written would not flag it.