feat(evm): opt-in short-circuit for future blocks without served-tip

common/config.go

@@ -2681,6 +2681,17 @@ type EvmNetworkConfig struct {
 	//     finalized head; an unfinalized block's empty is treated as not-yet-confirmed.
 	EmptyResultConfidence AvailbilityConfidence `yaml:"emptyResultConfidence,omitempty" json:"emptyResultConfidence,omitempty"`
 
+	// ShortCircuitFutureBlocks returns null for a numbered eth_getBlockByNumber
+	// above the highest latest head across every upstream of the network
+	// (regardless of selection policy, tier or syncing state), without
+	// dispatching it; it never fires while any upstream's head is unknown.
+	// Clients that poll the next block by number otherwise walk every routed
+	// upstream on each poll. Always on when servedTip is enabled for "latest".
+	// The head is what the state poller and head subscriptions last reported, so
+	// a block an upstream produced since then gets null until eRPC sees it: only
+	// enable it where heads arrive promptly (e.g. over WebSocket).
+	ShortCircuitFutureBlocks *bool `yaml:"shortCircuitFutureBlocks,omitempty" json:"shortCircuitFutureBlocks,omitempty"`
+
 	// SafeBlockSource is an upstream id/tag selector for standard JSON-RPC
 	// requests carrying the `safe` block tag. Matching upstreams define and
 	// serve `safe`; empty (without an inherited network default) keeps existing
@@ -2761,6 +2772,20 @@ type EvmServedTipConfig struct {
 	TrajectoryWindow *Duration `yaml:"trajectoryWindow,omitempty" json:"trajectoryWindow,omitempty"`
 }
 
+// ShortCircuitFutureBlocksEnabled reports whether a numbered eth_getBlockByNumber
+// above every upstream's head returns null without dispatching: when
+// ShortCircuitFutureBlocks is true, or servedTip is enabled for "latest".
+// Nil-receiver safe.
+func (c *EvmNetworkConfig) ShortCircuitFutureBlocksEnabled() bool {
+	if c == nil {
+		return false
+	}
+	if c.ShortCircuitFutureBlocks != nil && *c.ShortCircuitFutureBlocks {
+		return true
+	}
+	return c.ServedTipEnabledFor("latest")
+}
+
 // ServedTipEnabledFor reports whether the majority served tip is enabled for
 // the given block axis ("latest" or "finalized"). The "safe" tag resolves to the
 // finalized axis, so listing "safe" in EnabledFor enables it for "finalized".

common/config_test.go

@@ -1297,6 +1297,32 @@ func TestNetworkConfig_SetDefaults_StripSubscribeFromBlockZeroInheritsFromDefaul
 	assert.Equal(t, &strip, n.Evm.StripSubscribeFromBlockZero)
 }
 
+func TestNetworkConfig_SetDefaults_ShortCircuitFutureBlocksInheritsFromDefaults(t *testing.T) {
+	enabled, disabled := true, false
+	defaults := &NetworkDefaults{Evm: &EvmNetworkConfig{ShortCircuitFutureBlocks: &enabled}}
+
+	inherited := &NetworkConfig{Architecture: ArchitectureEvm, Evm: &EvmNetworkConfig{ChainId: 1}}
+	assert.NoError(t, inherited.SetDefaults(nil, defaults))
+	assert.True(t, inherited.Evm.ShortCircuitFutureBlocksEnabled())
+
+	// An explicit network-level false wins over a true default.
+	overridden := &NetworkConfig{Architecture: ArchitectureEvm, Evm: &EvmNetworkConfig{ChainId: 1, ShortCircuitFutureBlocks: &disabled}}
+	assert.NoError(t, overridden.SetDefaults(nil, defaults))
+	assert.False(t, overridden.Evm.ShortCircuitFutureBlocksEnabled())
+}
+
+func TestEvmNetworkConfig_ShortCircuitFutureBlocksEnabled(t *testing.T) {
+	var nilCfg *EvmNetworkConfig
+	assert.False(t, nilCfg.ShortCircuitFutureBlocksEnabled())
+	assert.False(t, (&EvmNetworkConfig{}).ShortCircuitFutureBlocksEnabled())
+	enabled, disabled := true, false
+	assert.False(t, (&EvmNetworkConfig{ShortCircuitFutureBlocks: &disabled}).ShortCircuitFutureBlocksEnabled())
+	assert.True(t, (&EvmNetworkConfig{ShortCircuitFutureBlocks: &enabled}).ShortCircuitFutureBlocksEnabled())
+	// servedTip for "latest" keeps the short-circuit on, as before.
+	assert.True(t, (&EvmNetworkConfig{ServedTip: &EvmServedTipConfig{EnabledFor: []string{"latest"}}}).ShortCircuitFutureBlocksEnabled())
+	assert.False(t, (&EvmNetworkConfig{ServedTip: &EvmServedTipConfig{EnabledFor: []string{"finalized"}}}).ShortCircuitFutureBlocksEnabled())
+}
+
 func TestUpstreamConfig_ValidateRateLimitCountMode(t *testing.T) {
 	cfg := &Config{}
 	base := func(mode RateLimitCountMode) *UpstreamConfig {

common/defaults.go

@@ -2280,6 +2280,9 @@ func (n *NetworkConfig) SetDefaults(upstreams []*UpstreamConfig, defaults *Netwo
 			if n.Evm.EmptyResultConfidence == 0 && defaults.Evm.EmptyResultConfidence != 0 {
 				n.Evm.EmptyResultConfidence = defaults.Evm.EmptyResultConfidence
 			}
+			if n.Evm.ShortCircuitFutureBlocks == nil && defaults.Evm.ShortCircuitFutureBlocks != nil {
+				n.Evm.ShortCircuitFutureBlocks = defaults.Evm.ShortCircuitFutureBlocks
+			}
 			if n.Evm.StripSubscribeFromBlockZero == nil && defaults.Evm.StripSubscribeFromBlockZero != nil {
 				n.Evm.StripSubscribeFromBlockZero = defaults.Evm.StripSubscribeFromBlockZero
 			}