newHeads over WebSocket.
For request-level monotonicity, use Block regression protection.
For related state reads at one block, use Read at one block.
HTTP and WebSocket observations
Each physical upstream instance has one block-sync worker for a chain, even when multiple profiles refer to it. The worker stores height, observation time, and source in the block-sync registry. Profiles sharing that instance also share its observations. HTTPeth_blockNumber polling follows the shortest positive head interval
requested by enabled references. monitoring.http_heads_interval_ms and
http_backup_interval_ms separate normal polling from polling while WebSocket
evidence is fresh; legacy probe_interval_ms supplies their fallback defaults.
background_observations: false disables that reference’s periodic work, and
0 disables an individual interval. Other references to a shared upstream can
still request observations. Client requests can supply evidence independently.
See monitoring settings.
The chain-level websocket.subscribe_new_heads setting defaults to true.
Providers inherit it unless they set their own subscribe_new_heads value.
A usable WebSocket connection is also required. See Profile configuration
and Provider configuration.
Comparing heights
Core ignores stale observations when deriving its chain reference height. With a measured block interval, it may give a bounded credit to an older observation before comparing heights. The reference is selected from the current, aligned provider samples; it is an operational routing estimate, not a consensus vote or proof of the canonical chain. A provider’s lag is compared with that reference. If a profile setsselection.max_lag_blocks, sufficiently lagging candidates can be excluded.
Unknown or stale data must not be read as verified head agreement. The
dashboard’s monitoring.lag_alert_threshold_blocks is a separate status
threshold; it does not set the routing limit.
The measured block interval uses an exponential moving average of increasing
heights. Until five valid samples are available, Core uses the configured
block_time_ms fallback. This helps account for observation delay on fast
chains, but it cannot turn a stale or incorrect upstream response into a
verified block.
Health probes
The probe coordinator checks upstream HTTP identity and health separately from block-height polling. Its 200 ms tick schedules work; it does not probe every provider five times per second. The effective provider cadence follows the shortest positive identity interval requested by enabled references, with failure backoff and jitter.chain_identity_interval_ms can disable identity
probing without disabling head observations. A matching eth_chainId probe can restore an HTTP
endpoint previously rejected for an identity mismatch. See Provider selection
for the remaining admission checks.
Operating guidance
- Configure
probe_interval_ms,block_time_ms, and lag limits for the chain’s actual cadence and your workload. Sharing a provider across profiles can change its effective polling cadence. - Compare provider heights and freshness by region before treating lag as a provider fault. A quiet log stream alone is not evidence of a dead connection.
- Verify a representative upstream-backed request; a healthy application endpoint does not prove that every provider is usable.