feat(uniswap-v3): event-source Mint/Burn liquidity (no RPC where warm)

[KaiCode2]

Event-source Uniswap V3 Mint/Burn liquidity (no RPC where warm)

Closes the largest reactive gap: V3 liquidity events previously always emitted a tick-range resync (an RPC round trip). They now event-source the affected state directly wherever it is already warm — matching the exact-write posture of the V2/Solidly Sync path — and resync only for ticks outside the warmed window.

Stacked on the tier-2 tip (hardening/tier-2-polish) so it inherits the pre-release hardening; retarget to main after the tier stack lands.

Mechanism

The event carries the exact liquidity delta (amount) and the boundary ticks; the current tick comes from cached slot0. For each warm boundary tick the adapter read-modify-writes:

• Tick.Info word 0 — liquidityGross (low 128) and liquidityNet (high 128, two's complement, opposite signs for the lower vs. upper tick).
• tickBitmap bit — toggled on an init/clear (Uniswap flipTick is an XOR); both ticks in a shared word are merged into one combined write.
• global liquidity — ±amount when the position straddles the current tick.

Those are exactly the slots a QuoterV2 swap reads. feeGrowthOutside and the positions mapping are accounting-only (they don't affect amountOut) and are intentionally not maintained.

A cold boundary tick (word 0 not cached) can't be read-modify-written, so its info + bitmap slots fall back to a VerifySlots resync — the hybrid write-where-warm / resync-cold policy. No-layout pools still degrade to a conservative whole-storage invalidation.

Correctness basis

• The reactive runtime applies each input's updates before the next input's decode (verified in evm-fork-cache's ingest_batch_direct), so read-modify-write sees earlier events in the same batch.
• Bitmap flips for two ticks in a shared word are accumulated into one write — two full-slot writes from the same pre-event view would not compose (a bug the shared-word burn test caught during development).

Tests

• 9 inline unit tests: packing round-trip (incl. negative liquidityNet), all four mint/burn × lower/upper sign combos, init/clear detection, burn-more-than-gross rejection, v3_bit_position vs Uniswap position (incl. negative ticks).
• Reactive integration: warm direct writes (liquidity + both ticks, no resync, quality Exact), out-of-range leaves global liquidity, burn-to-zero clears the shared bitmap word, and cold-tick resync fallback. PancakeSwap/Slipstream layout coverage retained (cold-resync targets the right layout).

Full offline gate green: tests (all-features / default / no-default), clippy -D warnings (all-features + no-default), doc -D warnings, fmt, missing_docs = 0.

Live RPC parity — verified ✅

tests/v3_liquidity_rpc.rs (env-gated, #[ignore]) validates against real chain state: for a real add- and remove-liquidity transaction it fetches the exact per-tx storage diff via trace_replayTransaction(stateDiff), warms the pre-tx state, applies the event through the adapter, and asserts our event-sourced writes reproduce the on-chain post-tx values.

Run live against a mainnet archive+trace endpoint on a JIT add+remove of the same liquidity on USDC/WETH 0.05% — both the Mint and the Burn reproduce the on-chain per-tx storage exactly: each boundary tick's packed Tick.Info word 0 (liquidityGross/liquidityNet, including a negative net in two's complement) and the in-range global liquidity.

MINT  tickLower.word0: matches on-chain 0x7c5dc4e0…7c5e19058bda42e0
MINT  tickUpper.word0: matches on-chain 0xffffffff…7c63a1c56379ba71
MINT  global liquidity: matches on-chain 0xca4544475ef4b80a
BURN  tickLower.word0: matches on-chain 0xffffffff…032d88bda42e0
BURN  tickUpper.word0: matches on-chain 0xffffffff…5bb986379ba71
BURN  global liquidity: matches on-chain 0x4de75e1a5ef4b80a

Built in an isolated git worktree off the tier-2 tip so it did not touch the concurrent Curve-bytecode-seeding work in the main working tree. Commit is unsigned (1Password SSH agent hung this session; pushed over HTTPS).

🤖 Generated with Claude Code