apollo_consensus_orchestrator,apollo_l1_gas_price: bound the per-block eth to fri rate change

[asaf-sw]

Bounds how far the ETH/FRI exchange rate may move from one block to the next, and clamps a fresh oracle rate into that band.

Why

The Chainlink oracle (#14942) guards each reading with absolute sanity bounds, but those are deliberately wide: the STRK/USD band spans five decades, because its job is wrong-feed detection. A manipulated but plausible feed value passes them. Only a bound relative to the previously accepted rate catches that, and #14944 names this bound as a precondition before any feed is flipped to the on-chain oracle.

Why the orchestrator and not the oracle client

A bound anchored to the Chainlink client's own last read is node-local history: two validators with different read histories would accept and reject different proposals, which is exactly what the original TODO ruled out.

The bound is implemented in apollo_consensus_orchestrator::utils, on the oracle-fetch path, where the previous block is already in hand. The anchor is the rate implied by the previous block's recorded wei and fri prices, derived with the existing calculate_eth_to_fri_rate. That makes the bound a function of the block header and of config alone: every validator derives the same band and maps a given oracle reading to the same rate. It also covers both oracle sources, HTTP and Chainlink, which a bound inside the Chainlink client would not.

The TODO in chainlink_oracle.rs is replaced with a comment pointing at where the relative bound now lives.

Clamp, not reject

A rate outside the band is clamped to the band's edge, following the shape of the existing per-block L2 gas price clamp (calculate_next_l2_gas_price_for_fin), including multiply-before-divide in U256 and a truncating division that makes the band marginally tighter, never looser. Clamping bounds per-block damage and forces a manipulation to be sustained across many blocks to move the price far.

Default

max_eth_to_fri_rate_change_ppt defaults to 50, i.e. 5% per block.

• Not too tight: the ETH and STRK feeds update on deviation thresholds of roughly 0.5% and 1%, so their ratio steps by at most ~1.5% between consecutive blocks. A normal feed update never trips the bound, so the metric stays at zero in healthy operation. A genuinely sharp market move is tracked within a few blocks.
• Not too loose: one manipulated reading moves the rate by at most 5%, and doubling it requires holding the feed for about 15 consecutive blocks (~40 seconds at mainnet block times), long enough for the oracle staleness alert (apollo_dashboard: alert on the Chainlink oracle guard trips #14948) and the guard-trip alert to fire.

No previous block

At startup, and on the path that falls back to the minimal config values, there is no anchor, so the oracle rate is used as is. That branch is explicit and commented rather than implicit.

Observability

Clamping increments consensus_eth_to_fri_rate_clamped (registered alongside its neighbours) and logs a warning naming the oracle rate, the previous block's implied rate, and the clamped result.

Config wiring

max_eth_to_fri_rate_change_ppt is on ContextDynamicConfig, and is present in the node config schema, consensus_manager_config.json, and replacer_consensus_manager_config.json (a param in the schema but missing from the app configs crash-loops every node).

Tests

utils_test.rs: rate inside the bound passes through unchanged; rate above the bound clamps to the ceiling; rate below clamps to the floor; boundary exactly at each edge is unchanged; no previous block means no clamping; the metric increments only when clamping; and two independently constructed instances, given the same previous block and the same oracle rate, produce the same result even when they have made a different number of oracle calls.

🤖 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_consensus_orchestrator,apollo_l1_gas_price: bound the per-block eth to fri rate change #14973 👈 (View in Graphite)
• apollo_dashboard: alert on the Chainlink oracle guard trips #14948
• apollo_l1_gas_price,apollo_l1_gas_price_config,apollo_node: select oracle source per feed #14944
• apollo_l1_gas_price,apollo_l1_gas_price_config,apollo_l1_gas_price_types: add Chainlink client #14942
• apollo_batcher: bound in-flight view calls so they cannot exhaust the blocking pool #14972 : 1 other dependent PR (#14979 )
• apollo_batcher: read class definitions through the class manager in view calls #14967
• main-v0.14.3

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