Implemented FARE447 and MedallionHook, with vendored dependencies, launch manifest, tests, and operational/security documentation.

Verified:

• forge build, forge test, and forge fmt --check
• Clean offline run: 44 tests passed
• Nine adapted protected checks passed
• Flags 0x10CC; zero forbidden opcodes

Mainnet dependencies were mocked locally; deployment assumptions and remaining verification responsibilities are documented.

Implemented FARE447, MedallionHook, offline dependencies, tests, and deployment documentation.

Verified:

• Offline build succeeds.
• All 90 tests pass.
• forge fmt --check passes.
• Corrected univ4_hook manifest passes schema validation.
• Flags are 0x10CC; forbidden opcode count is zero.

Deployment assumptions and responsibilities are documented in README.md and docs/. No transactions were broadcast.

Updated launch.json, clarifying retirement and IMD burn behavior.

Schema constraints, constructor ABI, permissions, and initial price checks passed. Notes are 1,637/4,000 characters. forge build succeeded with existing lint warnings; all 90 tests passed offline.

Only launch.json changed.

The review is complete. The findings file is written and the tree is untouched apart from the findings file and my scratch test, which git treats as ignored.

Outcome. No critical, high or medium defect in the Access Control, Trust Gap or Asymmetry area. The permission model is tight: no owner, setter, sweep, pause or upgrade exists, all four callbacks are gated on the immutable PoolManager, the unlock callback also demands the transient lock and a single-use payload hash, and the hook's ERC-6909 claims cannot be burned or moved by anyone else. The existing 90 tests pass.

Findings written to .imd-findings.json (each reproduced in test/scratch/Leads.t.sol):

1. Low, asymmetry. The constructor seeds the anchor from a POOL4 that answers but reports the market closed, while pokeAnchor() and burnIMD() refuse the identical state when pool4Seen is false. A hook deployed while POOL4 was unreadable has no burn path until the market opens once. The docs describe this as intended, so I flagged it as a decision for the author.
2. Low, liveness trust gap. Staleness keys on the last successful burn. After one burn and a gap over 50,400 blocks, normal mode is refused even though POOL4 is open and valid, and fallback requires the hookless plain ETH/IMD pool to exist. If it does not, both burn routes and pokeAnchor() revert until a third party creates and funds that pool. Spec-conformant, but the plain pool's mainnet existence is unverified.
3. Info, access × economics. The permissionless keeper can route the batch through a pool it controls and capture roughly 4% of each batch in normal mode, or about 14% in fallback, all within the spec's constants. Recorded as the trust assumption behind permissionless keeping, with no change proposed.

Coverage. All 12 listed entry points have rows: 10 hold, burnIMD and pokeAnchor carry the findings. The slither and aderyn leads were checked and rejected with reasons in the coverage rows. The one thing I could not verify offline is the behaviour of the three mainnet constants: the NFT contract's transfer rules, the POOL4 hook's marketOpen()/refTick() semantics, and whether the plain pool exists.

Review complete. No tracked file was changed. The findings are in .imd-findings.json with a 15-row coverage record, and the project suite still passes 90 of 90.

What I found

1. High: burn reference deadlock. The staleness clause at src/MedallionHook.sol:370 turns normal mode off once a burn is older than 50,400 blocks. The only way back is a successful burn, but the only burn still offered is the fallback one, whose anchor is clamped to the last reference ±1000 ticks, and that reference is refreshed only in normal mode. If IMD has fallen more than ~11% since the last burn, both routes revert forever (Pool4Unavailable and PriceOffReference) while POOL4 is open and answering. All further fees pile up as claims with no recovery route. The implementation follows the spec text literally, so fixing it is a scope decision. The attached proof under test/scratch/StaleBurnDeadlock.t.sol fails on the current code and passes when the staleness gate is removed from the reference check. I verified the pass by temporarily editing the source and restoring it from git.

2. Low: launch pool hijack on non-atomic deployment. Any first native-ETH pool becomes the permanent fee pool. Confirmed against the real PoolManager. Only reachable if the hook has code before the factory initializes its pool.

3. Low: creator reserve stranded if the medallion cannot be resolved. If token 447 is burned or the NFT contract disappears, retire reverts MedallionUnavailable forever and the 1.64 ETH stays locked. Spec-conformant, but worth the owner's attention.

What held

• All four swap fee modes against v4-core 1.0.2 delta semantics, PartialFill checks, and claim minting.
• The ledger invariant, the creatorPaid 0-or-cap rule, the single Recouped emission, retire atomicity and reentrancy, and unlockCallback binding.
• Burn sandwich economics are bounded by the 4% slippage floor and small batches, not profitable at normal liquidity.

Not reached: mainnet facts I could not verify offline, namely IMD decimals and transfer-to-DEAD behaviour, the POOL4 hook's actual marketOpen/refTick semantics, and whether the plain ETH/IMD 1% pool exists. These are leads, not findings.

Added failure-path, fuzz, and stateful invariant tests for token accounting, retirement, burn guards, and unlock security. Only test/ changed.

Offline validation passed: forge build and forge test — 128 tests passed, zero failures or skips.

No confirmed contract defects found.

The math audit is complete and the findings file is written. The working tree is clean apart from the ignored findings file, and the scratch tests are removed.

Outcome. No material arithmetic defect was found in the assigned area. One low-severity, spec-consistent seam is recorded, with measured numbers, in .imd-findings.json.

What I verified

• Swap fees, all four modes. Traced the v4-core 1.0.2 delta path (Hooks.beforeSwap, Hooks.afterSwap, Pool.swap) and fuzzed 3000 runs against a real PoolManager from 1 wei to 1e21 wei. The ledger equals |amount|/50 in the two specified-ETH modes and gross/50 in the two unspecified modes, the user's ETH delta is exactly the specified amount, and the PartialFill equality is exact because the pool's remaining amount reaches zero on a full fill. The int128 range check precedes negation, so no cast can wrap.
• Quote arithmetic. Both _quote branches and negative ticks were exercised with real burns at ticks -120000, 60405 and 460000. Outputs match amount × 1.0001^tick less the 1% LP fee. The high branch has no overflow even at the maximum tick, and ticks above about 443636 are unreachable for a 0.05 ETH batch since the IMD leg exceeds int128.
• Anchor stepping. The band clamp and the step clamp keep the anchor between the last reference and the spot, so it can never leave the valid tick range. That lead is dead.
• Ledger and retirement. burnSpent can never exceed totalFees - CAP, so the hook always holds at least the cap in claims when retirement is allowed. Status formatting truncates correctly at two and one decimals.
• External boundaries on mainnet. Via the operator's keyed RPC: POOL4_HOOK answers marketOpen true and refTick 60405, both fixed burn pools are initialized, and the plain pool holds about 7.7e21 liquidity. The references and routes the burn math depends on are live.

The one finding (low). The minimum-output floor is 96% of the quote at the reference tick, while the guard is one-sided. When the reference lags below the plain spot, a sandwich can push spot down to reference minus 299 ticks and let the burn complete at the reference floor. Measured on a real PoolManager with spot 500 ticks above reference: the hook received 0.04804 IMD for 0.05 ETH against 0.05257 fair, an 8.6% shortfall rather than the 4% a reader of MAX_SLIPPAGE_BPS expects. The loss is bounded per batch and non-compounding, and the formula is exactly what the spec prescribes, so it is recorded as a design-limit note for the author.

Coverage. All 12 listed entry points have rows: 11 hold, burnIMD references the finding. Four extra rows cover the claims invariant, status formatting, both quote branches, and fee rounding direction. The static-analysis leads (strict block equality, reentrancy ordering in retire, uninitialized fee, unused slot0 return) were each checked and none is a defect.

Not reached. The POOL4_HOOK's own fee schedule could not be read offline. If it charges more than about 1.8% on top of the LP fee, the POOL4 route would trip the Slippage floor whenever spot sits 150 ticks below reference. That is a liveness question for the deployer, not a loss.

Review complete. The findings file is written and validated, the proof fails on the current tree and passes under a spec-preserving fix, and src/ is byte-identical to the commit.

What I audited. The Execution Trace, Periphery and First Principles passes over src/MedallionHook.sol and src/FareToken.sol, traced against the vendored v4-core (Hooks.sol, PoolManager.sol, Pool.sol, StateLibrary.sol). All four swap fee modes, claim minting and delta netting, retirement, the unlock-callback binding, the transient lock, status strings, and the token were traced with concrete values and probed on a real PoolManager. The existing 90-test suite passes.

Findings written to .imd-findings.json:

1. High: the stale-burn rule can permanently deadlock burning while POOL4 is live. After one burn and 50,400 quiet blocks, _normalReference() at src/MedallionHook.sol:370 reports "not normal" even though POOL4 is open and answering. The only way back is a successful fallback burn, but fallback is pinned to the plain pool and the stale anchor band. If the plain pool is absent or illiquid, or the market drifted more than 1,150 ticks below the stale reference, every burnIMD and pokeAnchor reverts forever and surplus fees are frozen. The proof at test/scratch/StaleDeadlock.t.sol reproduces both variants on a real PoolManager (fails with Pool4Unavailable now, passes after letting pokeAnchor re-seed from a live POOL4 and counting that seed as fresh).

2. Low: a same-block POOL4 re-seed is discarded by fallback. _seedAnchor snapshots the previous anchor rather than the reference just read (src/MedallionHook.sol:405-407). If the market closes later in the same block, a fallback burn is guarded and quoted against a reference up to 1,000 ticks stale. Measured on a real manager: output 0.00976 IMD against 0.01105 fair at the fresh reference, on a 0.01 ETH batch.

Coverage. All 12 listed entry points have rows, plus 4 invariant rows. Ten entry points hold; burnIMD and pokeAnchor carry finding 1. Slither and Aderyn leads (strict equality in _stepAnchor, reentrancy in retire, unused return in _spot) were traced and are intentional or guarded, so none became a finding.

Not reached. Economic sizing of the fallback band and tolerance constants, and whether the mainnet POOL4 hook actually exposes marketOpen() and refTick() or whether the plain ETH/IMD pool exists, which only a mainnet fork can answer.

Review complete. The findings file is written and validated against the tree.

Outcome: one high finding, two lows, three infos, all reproduced; coverage answers all 12 entry points plus five invariant rows.

• High (finding 1, src/MedallionHook.sol:370): the stale-burn clause in the normal-mode test ignores a live, open POOL4 once a burn is older than 50,400 blocks. Fallback can only move the anchor within lastRef ± 1000 and refuses spot below reference − 150, so after a week without a keeper call and an ~11% move in IMD/ETH no burn route can ever succeed again, and every surplus fee strands in the hook's claims with no sweep. This merges the economics and flow highs and the permissions liveness lead, which share the root cause. I confirmed mainnet state today: POOL4 open at refTick 60281 and both burn pools live, so the price-drift variant is the reachable one. The attached proof test fails on the tree and passes in a copy with the clause removed. I noted that the code follows the spec's wording, so the fix is a scope decision.
• Low (finding 2, line 228): the output floor uses the reference only and the guard is one-sided, so up to ~8% of a batch can be captured when the market sits above the reference. Merged audit_math with the permissions keeper note. Measured 7.7% shortfall in a mock.
• Low (finding 3, line 406): a normal-mode re-seed keeps the pre-seed anchor as the block's fallback reference. Measured 10.8% overpay on a same-block fallback burn after the market closes.
• Info (findings 4 to 6): closed-market seeding asymmetry, first-native-pool binding, and the stranded reserve if the NFT becomes unresolvable. All are spec-literal or documented, and I kept them so the record shows they were weighed.

Nothing new surfaced from my own pass over the swap accounting, retire path, unlock callback binding, ledger invariant, constants, status strings, manifest and token. The existing suite passes 128 of 128. The one row I left unreached is whether the live POOL4 hook accepts swaps from this hook as sender, which only affects route choice, not liveness.

Fixed stale-burn recovery through pokeAnchor() without resetting the burn cooldown. Added 10 regression tests.

All six findings are answered in .imd-responses.json. Advisory behaviors required by the spec were reproduced, retained, and documented.

Validation passed: forge build, forge test (100 passed), and forge fmt --check. The manifest retains "kind": "univ4_hook".

the task produced no changes; the agent's last message was: Existing launch.json already satisfies the supplied schema and matches the implementation. No revision was needed.

• Constructor, permissions, metadata and pool settings verified.
• Notes: 1,637/4,000 characters.
• Offline forge build passed.
• Offline forge test: 100 passed, zero failures.
• No tracked files changed.

Updated only launch.json, clarifying Cancun compatibility, required hook address bits and mainnet-only operations.

Schema constraints, constructor, metadata and permissions verified. Notes: 1,858/4,000 characters.

Offline forge build passed; forge test passed all 100 tests.

Done. Everything is in place and verified, with one pre-existing problem found and fixed along the way.

What I delivered (all under test/)

• test/mocks/Pool4HookMock.sol: a v4-callable stand-in for the POOL4 CappedBurnHook, meant to be etched at the fixed POOL4 address. That address carries flags 0x2840, so a real PoolManager drives beforeInitialize, beforeAddLiquidity and afterSwap on it. It also answers the two oracle views with switchable failure modes.
• test/Pool4Route.t.sol: 11 real-PoolManager tests of the POOL4 route, which no earlier suite ran outside a scripted manager mock. Burns settle through the exact fixed key, the POOL4 hook's own revert aborts a burn atomically, an uninitialized burn pool fails before any unlock, closed and malformed oracles leave only the plain fallback, real price moves exercise the one-sided guard at 150 and 300 ticks, the once-per-block 200-tick fallback step and its 1000-tick band, stale-then-poke recovery, and the slippage floor against thin liquidity and caller minimums.
• test/BurnReferenceInvariant.t.sol: an invariant campaign on a real PoolManager with both fixed IMD pools. Random fee accrual, price moves on either pool, five oracle states, block gaps including 50,401 idle blocks, burns on both routes and pokes. A ghost model of spec section 7 predicts which guard refuses each burn or that it reaches the swap, and after every call the hook's anchor, references, blocks and ledger must equal the model, so every rollback is checked. A scratch reachability run confirmed every outcome bucket is populated.
• test/PROPERTIES.md documents the new suites.

Pre-existing flake fixed

The full suite was failing intermittently in MedallionLifecycleInvariant.t.sol with forge's misleading "failed to set up invariant testing environment" message. The verbose trace carried the real cause: a handler assertion, where the hook spent a 0.05 ETH normal batch but the ghost model expected a 0.01 ETH stale batch. The handler measured staleness from the last burn only and ignored that a live pokeAnchor re-seeds the reference block. That behaviour is the accepted stale-recovery revision recorded in docs/security-review.md, so the model was wrong, not the hook. I corrected the model, added the reference block to the invariants, and extended the deterministic witness with the burn, idle, poke, burn sequence. The suite now passes 5 of 5 runs alone and the full suite 3 of 3.

Verification

forge build --offline   OK
forge fmt --check       OK
forge test --offline    12 suites, 151 tests passed, 0 failed

No .imd-findings.json was written. I found no implementation defect that cannot be tested. The one spec-literal deviation, a live poke restoring normal mode after a stale period, is a documented and previously accepted revision rather than a defect.

Round 2 is settled with no outstanding findings: .imd-findings.json holds {"findings":[]} plus 19 coverage rows (all 12 entry points answered holds, 7 extra rows for round-1 settlements, invariants and the manifest).

The high finding is fixed. The stale-burn deadlock (eaad7c91) no longer reproduces:

• What changed: pokeAnchor() now seeds the anchor and last reference from a validated, open POOL4 whatever the burn history, and a new lastReferenceBlock counts that seed as fresh in _normalReference() (src/MedallionHook.sol:242-244, 373-374, 416).
• Re-run of my round-1 steps: one burn at block 105, 50,401 idle blocks, POOL4 and both pools at -1500, 30 pokes. lastRefTick and anchorTick now follow to -1500, and both burnIMD(true,0) and burnIMD(false,0) succeed (burnSpent goes from 0.05 to 0.10 ETH).
• Other cases checked:
  • Recovery after POOL4 was closed and then reopened works with a single poke.
  • A poke before any burn followed by long idle is harmless.
  • Without a poke the stale state still reverts Pool4Unavailable / PriceOffReference, as documented, and a same-block poke recovers it.
• The changed lines introduce nothing new:
  • lastReferenceBlock is written only by the constructor seed and _seedAnchor.
  • It cannot underflow.
  • It does not touch the cooldown or the ledger.
  • Fallback steps and closed or malformed POOL4 answers cannot refresh it.

The advisories are settled and not restated. All five still behave as I described, the author reproduced each, and each is what the spec's wording requires; the limits are now written into docs/operations.md and docs/security-review.md.

• Reference-only 96% floor, one-sided guard (0991a35a): spec 7's formula and constants.
• Same-block re-seed keeps the earlier snapshot (13988683): my scratch test confirms it still happens, but spec 7 says "anchor at the start of the block", so the author's reading is the literal one. Exposure is one 0.01 ETH batch.
• Constructor seeds from a closed POOL4, later first seed needs an open one (2088f5bf): deployment precondition.
• First native-ETH pool binds launchPool (14682a3f): spec 2; needs atomic deploy-and-initialize.
• Destroyed NFT locks the 1.64 ETH reserve (d3fb4425): spec 6.

Verification: forge test --offline passes 151 of 151, and my six scratch tests passed. Of the advisories, I re-ran only the same-block re-seed one; for the other four I relied on the author's stated reproductions and the unchanged code.

Not done: the protected floor tests in .imd/reads/protected/ were not run, because they import verifier-side files (HookFlags.sol, MockERC20.sol) that are not in this tree. No Slither, Aderyn or fork runs; the supplied static-analysis lines were checked by reading and none is a defect.

No tracked file was changed; test/scratch/ was removed after use.