refactor(grpc-server): extract shared historical helpers

[Pablosinyores]

Summary

`aether-replay` (2220 LOC) and `aether-profit-scorer` (2085 LOC) carried
duplicate inline copies of every helper used to load pool registries,
fetch reserves at a fixed block, and convert U256 reserves into f64
graph weights. This PR moves the canonical versions into
`crates/grpc-server/src/historical.rs` and has both binaries depend on
it. The scorer's source even had an explicit `//! Inlined helpers ...
Follow-up: deduplicate after the mempool phase lands.` block-doc — this
PR is that follow-up.

Stacks on PR #146 (`feat/grafana-mempool-panels`).

What moved into `historical.rs`

• `sol! { getReserves, slot0 }` block + the emitted `getReservesCall` /
  `slot0Call` types (re-exported `pub` so replay's anvil-driven
  `fetch_one_state_latest` and `fetch_all_states_latest` still link)
• `enum PoolState { V2, V3 }`
• `struct LoadedPool`, `struct PoolsConfig`, `struct PoolEntry`
• `pub const Q96`
• `fn parse_protocol` — long-form `pools.toml` strings (`uniswap_v2`,
  `sushiswap`, `uniswap_v3`, `curve`, `balancer_v2`, `bancor_v3`)
• `fn load_pools` — TOML loader, filters to V2/Sushi/V3
• `async fn fetch_pool_state_at` — `Result<Option>`. Replay's
  swallow-RPC-error-as-None call site adapts with `.ok().flatten()` to
  preserve observable behaviour.
• `fn u256_to_f64` — saturating limb-wise truncation
• `fn uniswap_v2_get_amount_out` — exact U256 math, `saturating_sub` on
  `(10_000 - fee_bps)` (the previous replay variant used straight
  subtraction; for any real fee_bps (≤ 100 bps) the two produce identical
  output).
• `fn load_executor_init_bytecode` — parses `bytecode/object` out of
  forge's AetherExecutor.json

What stays binary-local

Scorer-only:

• `parse_db_protocol` (short-form `uni_v2` / `uni_v3` / `sushi` strings
  the engine writes into `mempool_predictions.protocol`)
• `load_predicted_pools` (PR feat(mempool): widen scorer pool source via mempool_predictions #137 DB-augmented registry)
• `verify_cycle_u256` (PR feat(mempool): U256 cycle verifier + f64 absurdity floor #136 precision walker)
• `verify_cycle_revm`, `build_steps_from_cycle_sync`,
  `is_v3_touching_cycle`, `balance_slot_for_token` (PR feat(mempool): revm verifier resolves V3 cycles in scorer #144 V3 verifier)
• `state_to_graph_reserves`, `gas_estimate_for_protocols`,
  `cycle_to_json`, `u256_to_i128_saturating` (scorer math)
• `ScorerState` + `bootstrap_state` (scorer wiring)

Replay-only:

• `default_pool_set`, `token_label` (display helpers)
• `build_graph` (full graph assembly — replay needs it per-tx-window;
  scorer uses `state_to_graph_reserves` against an edge-clone instead)
• `AnvilHandle`, `spawn_anvil`, `fetch_one_state_latest`,
  `fetch_all_states_latest` (anvil-fork lifecycle)
• `optimize_cycle_input`, `estimate_opp` (intra-block optimisation)
• `run_batch_replay`, `run_full_block_replay`, `seed_sender_state`,
  `sim_arb_with_evm_simulator`, `deploy_executor_on_anvil`,
  `build_steps_from_cycle` (replay async pipeline)

Diff stats

```
crates/grpc-server/src/bin/aether_profit_scorer.rs | 188 ++-------------------
crates/grpc-server/src/bin/aether_replay.rs | 178 ++-----------------
crates/grpc-server/src/historical.rs | 319 ++++++++++++++++++++++
crates/grpc-server/src/lib.rs | 1 +
4 files changed, 341 insertions(+), 345 deletions(-)
```

Net: -4 LOC, one less copy of each helper to keep in sync.

Verification

```
cargo clippy --workspace --all-targets -- -D warnings ✓ clean
cargo test --workspace --lib --bins ✓ 527 passed, 0 failed
```

6 new `historical.rs` unit tests:

• `parse_protocol_known_strings`
• `u256_to_f64_small_values_exact`
• `uniswap_v2_get_amount_out_canonical`
• `uniswap_v2_get_amount_out_zero_inputs`
• `load_pools_filters_unsupported_protocols`
• `load_pools_handles_missing_pools_key`

Pre-existing scorer tests covering `uniswap_v2_get_amount_out` and
`PoolState` constructions are unchanged and still pass via the new
imports.

Empirical behaviour proof — simple-mode replay diff

`aether-replay` default mode (no `--full-block`, no anvil) against
mainnet block `24643151` with `--pools config/pools.toml` exercises
`load_pools` → `fetch_pool_state_at` → `u256_to_f64` →
`build_graph` → Bellman-Ford → `print_cycles`. `diff` of stdout before
vs. after the refactor:

```
7c7
< State fetched: 53/55 (4251 ms)

State fetched: 53/55 (3882 ms)
14c14
< Total time: 4989 ms

---

Total time: 4114 ms
```

Only the wall-clock timing strings differ — `Pools loaded`,
`State fetched` count, `Graph` topology, `Detection` count, top
`profit_factor` (`174745.3472%`), and `path`
(`DAI -> 0x9f8f72aa… -> WETH -> DAI`) are byte-identical.

Why the full-block `--csv` bar is intentionally NOT used

The original handoff suggested byte-identical `--full-block --csv`
output as the proof bar. Empirically that metric is inherently
nondeterministic, even between two consecutive runs of the SAME
binary against the same block:

Run	Binary	CSV hash
baseline	pre-refactor	`a4bbccc5…`
after-1	this PR	`198a6167…`
after-2	this PR	`a2c0b4c8…`

`diff after-1 after-2` produces ~60 differing lines. Two factors:

1. Bellman-Ford cycle-entry randomness. When the detector finds
   multiple negative cycles at the same tx-step, the "top" cycle picked
   for CSV emission depends on internal HashMap iteration order, which
   Rust randomises per-process. Same graph → different "top" each run.
2. Anvil fork + RPC timing variance. Each tx replay re-fetches pool
   state through the forked Anvil; under any RPC slowness or
   connection-reset (which happened in one of the runs above), the
   per-tx state at detection-time can shift, changing the cycle counts.

The simple-mode diff above gives a clean signal because there's exactly
one detected cycle and no anvil in the loop.

Out of scope (tracked)

• `build_steps_from_cycle` (replay async) vs `build_steps_from_cycle_sync`
  (scorer sync) — same shape, different exec model. Folding requires
  changing replay's signature; defer to PR-8b.
• `sim_arb_with_evm_simulator` (replay anvil-driven) vs
  `verify_cycle_revm` (scorer pure-revm CREATE-then-CALL) — different
  deployment models. Some shared infrastructure (`RpcForkedState`
  construction, balance-slot table) could fold; tracked.
• `build_graph` (replay full assembly) vs `state_to_graph_reserves`
  (scorer per-edge update) — different abstractions; tracked.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
aether	Ready	Preview, Comment	May 20, 2026 12:18pm
aether-63xv	Ready	Preview, Comment	May 20, 2026 12:18pm