feat(simulator): opt-in state-override stream for pAMM-aware settlement simulation

[louisponet]

Problem

Titan's propAMMs (pAMMs) hold their live prices in maker quote streams. The CoW driver simulates every solver solution before scoring (gas estimation via eth_estimateGas against a plain node), and the trade verifier simulates proposed quotes the same way — both without any state overrides.

Titan publishes a public pAMM state stream: eth_call-style state-override sets over websocket (wss://{eu,ap,us}.rpc.titanbuilder.xyz/ws/pamm_quote_stream, no auth, ~100–400 ms cadence), plus an HTTP snapshot method titan_getPammStateOverrides. Without applying the overrides, a node sim only sees the pAMM's last-committed-block storage.

Ref: https://docs.titanbuilder.xyz/propamms/takers#pamm-state-stream

Approach

A generic, fully opt-in "simulation state-override stream" feature. The wire format is exactly Ethereum's standard State Override Set, so nothing Titan-branded lives in code — the Titan endpoint appears only in example.toml comments and this PR description. When the config section is absent: no task is spawned, and the RPC override parameters are omitted entirely — byte-identical behavior to today.

The stream module (crates/simulator/src/state_override_stream.rs) spawns a background tokio task that connects to the websocket, parses per-venue frames, and flattens them into one StateOverride (latest frame wins per account, matching the builder's pamm_quote_stream accumulator design). It publishes via tokio::sync::watch; SimulationOverrides::current() gates on staleness (local receive time, not the producer wall-clock frame timestamp) and block lag, returning None so callers omit the RPC params entirely on a stale/unconfigured stream. Reconnect uses exponential backoff (250 ms → 15 s cap). Prometheus metrics cover frames, parse failures, reconnects, account count, and simulations_with_overrides{applied,stale}.

Next-block pinning

current() also returns BlockOverrides { number: head+1, time: head_timestamp + chain_block_time }. The stream frame's top-level timestamp is the producer wall clock (nanoseconds), not block time, so the next-block timestamp is derived from the current head block's timestamp plus Chain::block_time_in_ms() instead. This pins the simulation to the next block — the block context the streamed venue state is intended for.

Backends

• Ethereum: estimate_gas gains Option<StateOverride> + Option<BlockOverrides> via overrides_opt / with_block_overrides_opt (None omits the RPC params). Requires a node supporting eth_estimateGas state/block overrides (geth ≥1.13, reth, nethermind, recent erigon, anvil).
• Tenderly: simulate gains Option<StateOverride>; nonce is stripped inline (Tenderly's StateObject::try_from rejects it, pAMM frames always carry it, and contract nonces only matter for CREATE). Full-state overrides are left for try_from to reject.
• access_list(): unchanged — the access-list probe is a 1-wei ETH transfer that never touches pAMM state, and create_access_list has no override support.

Trade verifier

SettlementSimulator gains an optional SimulationOverrides handle. finish_simulation_builder appends streamed overrides as AccountOverrideRequest::Custom so build_final_state_overrides' existing merge + conflict handling arbitrates against the verifier's own overrides (solver code, trader balance/approval slots). Block overrides are forwarded into EthCallInputs and applied in simulate() (eth_call) and simulation_report() (debug_traceCall). The shared SettlementSimulator covers both the trade verifier and the orderbook order-creation simulator.

Config

# [simulator.state-override-stream]
# ws-url = "wss://eu.rpc.titanbuilder.xyz/ws/pamm_quote_stream"
# max-age = "3s"        # ignore the snapshot if the last frame is older than this
# max-block-lag = 1     # ignore the snapshot if its block number lags head by more than this

The same optional section is added to the price-estimation config for the trade-verifier path.

Tests

• 9 hermetic unit tests: frame parsing (verbatim Titan sample + real frames captured from wss://eu.rpc.titanbuilder.xyz/ws/pamm_quote_stream), per-account flattening across venues, latest-wins conflict handling, all three staleness gates, and an in-process WebSocket server reconnect/accumulation test.
• 2 #[ignore]'d anvil integration tests: deploy a contract reverting unless storage slot 0 is nonzero, assert estimate_gas reverts without the override and succeeds with it, and that block overrides are accepted.

[github-actions]

All contributors have signed the CLA ✍️ ✅
_{Posted by the CLA Assistant Lite bot.}

[louisponet]

I have read the CLA Document and I hereby sign the CLA

[louisponet]

recheck

[gemini-code-assist]

Warning

Gemini encountered an error creating the review. You can try again by commenting /gemini review.

[jmg-duarte]

Didn't finish reviewing yet but this is the lowest hanging fruit

[MartinquaXD]

The overall idea of the code (manage updates in background task and expose latest state via watcher) makes a lot of sense to me.
Just seems like the current PR could be simplified further.

[MartinquaXD]

Instead of forcing the caller to tell us the current block the SimulationOverrides could also store its own CurrentBlockWatcher.

And more importantly since updates get streamed on a sub-block interval does it even make sense to think in terms of blocks here?

[louisponet]

So the only reason this is kept at all is for setting it when simulating. As long as the simulator sets timestamp and blocknumber correctly to the next one, it's ok. I have removed all of this