apollo_l1_events,apollo_l1_events_config: chunk L1 getLogs range into bounded windows (M-25)

[asaf-sw]

M-25 — Chunk the L1 getLogs range into bounded windows

Security review finding: M-25 (Low–Medium). The L1 events scraper built the inclusive range scraping_start..=latest_l1_block and asked the base layer for all tracked events across that entire range in a single events() / eth_getLogs call, with no per-iteration cap and no chunking (a // If this gets too high, send in batches. comment acknowledged the gap). After downtime, an L1 outage, or with a large startup rewind, that range can span thousands of L1 blocks. The dominant failure mode is a liveness stall: the single call is wrapped in a 1 s timeout plus an N+1 per-event header fetch, so an oversized range times out and the scraper spins in its retry loop, never advancing — and (via the cyclic wrapper) misfires the primary-down-since signal. Unbounded Vec<L1Event> / Vec<Event> materialization is a secondary memory risk.

What changed

• New config param l1_events_scraper_config.max_blocks_per_fetch: u64 (apollo_l1_events_config), default 1000, validated >= 1.
• Bounded fetch window (apollo_l1_events/src/l1_scraper.rs): fetch_events now requests scraping_start..=min(latest, start + max_blocks_per_fetch - 1) and returns the L1BlockReference for the window end, so the cursor advances by exactly one window per poll and the steady-state loop drains a backlog over successive polls. The finality ceiling and the once-per-poll reorg check are preserved. initialize sends the first bounded window via the provider's initialize() and lets the steady loop drain the rest via add_events, so the provider's initialize-once contract is unchanged. Saturating arithmetic guards a 0 cap even though validation rejects it.
• Deployment presets updated. l1_events_scraper_config.max_blocks_per_fetch: 1000 added to the hand-maintained l1_events_scraper_config.json and replacer_l1_events_scraper_config.json presets, and config_schema.json regenerated. A new required schema param missing from the presets would MissingParam-panic the deployed node at startup (CrashLoopBackOff in system_test_hybrid) — exactly the bug L-16 (apollo_l1_events: bound catch-up commit-block backlog with a cap and metric #14590) hit.

Assumptions (documented in code)

Default 1000 is conservative versus common public-RPC eth_getLogs caps (~1k–10k) and the 1 s timeout; operators on private RPCs may raise it.

Tests

SEED=0 cargo nextest run -p papyrus_base_layer -p apollo_l1_events -p apollo_l1_events_config — 125 passed (new: range-cap, partial-window, finality-ceiling, multi-poll backlog drain). cargo nextest run -p apollo_deployments (incl. deployment_files_are_up_to_date) and -p apollo_node_config (default_config_file_is_up_to_date) both pass.

🤖 Generated with Claude Code

[reviewable-StarkWare]

This change is 

[asaf-sw]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• apollo_l1_events,apollo_l1_events_config: chunk L1 getLogs range into bounded windows (M-25) #14602 👈 (View in Graphite)
• papyrus_base_layer,apollo_l1_events: classify transient vs permanent L1 errors (L-13) #14601
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.