add update

Author: tac0turtle

crates/node/src/builder.rs

@@ -192,16 +192,7 @@ where
             .finish(&state_provider)
             .map_err(PayloadBuilderError::other)?;
 
-        let mut sealed_block = block.sealed_block().clone();
-
-        // Legacy mode: preserve historical behavior where the Engine API block hash did not match
-        // the canonical keccak header hash. We intentionally re-seal with an alternate hash while
-        // keeping the Ethereum `state_root` intact for normal state-root validation.
-        if !self.config.is_hash_rewire_active_for_block(block_number) {
-            let legacy_hash = sealed_block.header().state_root;
-            let legacy_block = sealed_block.clone_block();
-            sealed_block = SealedBlock::new_unchecked(legacy_block, legacy_hash);
-        }
+        let sealed_block = block.sealed_block().clone();
 
         tracing::info!(
                     block_number = sealed_block.number,

crates/node/src/config.rs

@@ -21,9 +21,32 @@ struct ChainspecEvolveConfig {
     /// Block height at which the custom contract size limit activates.
     #[serde(default, rename = "contractSizeLimitActivationHeight")]
     pub contract_size_limit_activation_height: Option<u64>,
-    /// Block height at which canonical hash rewiring activates.
-    #[serde(default, rename = "hashRewireActivationHeight")]
-    pub hash_rewire_activation_height: Option<u64>,
+    /// Block height at which canonical block hash enforcement activates.
+    ///
+    /// # Background
+    ///
+    /// Early versions of ev-node passed block hashes from height H-1 instead of H
+    /// when communicating with ev-reth via the Engine API. This caused block hashes
+    /// to not match the canonical Ethereum block hash (keccak256 of RLP-encoded header),
+    /// resulting in block explorers like Blockscout incorrectly displaying every block
+    /// as a fork due to parent hash mismatches.
+    ///
+    /// # Migration Strategy
+    ///
+    /// For existing networks with historical blocks containing non-canonical hashes:
+    /// - Set this to a future block height where the fix will activate
+    /// - Before the activation height: hash mismatches are bypassed (legacy mode)
+    /// - At and after the activation height: canonical hash validation is enforced
+    ///
+    /// This allows nodes to sync from genesis on networks with historical hash
+    /// mismatches while ensuring new blocks use correct canonical hashes.
+    ///
+    /// # Default Behavior
+    ///
+    /// If not set, canonical hash validation is enforced from genesis (block 0).
+    /// This is the correct setting for new networks without legacy data.
+    #[serde(default, rename = "canonicalHashActivationHeight")]
+    pub canonical_hash_activation_height: Option<u64>,
 }
 
 /// Configuration for the Evolve payload builder
@@ -47,17 +70,32 @@ pub struct EvolvePayloadBuilderConfig {
     /// Block height at which the custom contract size limit activates.
     #[serde(default)]
     pub contract_size_limit_activation_height: Option<u64>,
-    /// Block height at which canonical hash rewiring activates.
+    /// Block height at which canonical block hash enforcement activates.
+    ///
+    /// # Background
+    ///
+    /// Early versions of ev-node passed block hashes from height H-1 instead of H
+    /// when communicating with ev-reth via the Engine API. This caused block hashes
+    /// to not match the canonical Ethereum block hash (keccak256 of RLP-encoded header),
+    /// resulting in block explorers like Blockscout incorrectly displaying every block
+    /// as a fork due to parent hash mismatches.
+    ///
+    /// # Migration Strategy
+    ///
+    /// For existing networks with historical blocks containing non-canonical hashes:
+    /// - Set this to a future block height where the fix will activate
+    /// - Before the activation height: hash mismatches are bypassed (legacy mode)
+    /// - At and after the activation height: canonical hash validation is enforced
+    ///
+    /// This allows nodes to sync from genesis on networks with historical hash
+    /// mismatches while ensuring new blocks use correct canonical hashes.
     ///
-    /// Before activation, ev-reth operates in "legacy" mode to support deployments that flowed an
-    /// application-level hash through Engine API payloads. In that mode the node may bypass block
-    /// hash mismatches and re-seal blocks with an alternate hash for compatibility.
+    /// # Default Behavior
     ///
-    /// After activation, the node enforces canonical keccak block hashes as expected by standard
-    /// Ethereum tooling. Note that `header.state_root` always follows Ethereum semantics (the
-    /// current block's post-state root), independent of this setting.
+    /// If not set, canonical hash validation is enforced from genesis (block 0).
+    /// This is the correct setting for new networks without legacy data.
     #[serde(default)]
-    pub hash_rewire_activation_height: Option<u64>,
+    pub canonical_hash_activation_height: Option<u64>,
 }
 
 impl EvolvePayloadBuilderConfig {
@@ -70,7 +108,7 @@ impl EvolvePayloadBuilderConfig {
             mint_precompile_activation_height: None,
             contract_size_limit: None,
             contract_size_limit_activation_height: None,
-            hash_rewire_activation_height: None,
+            canonical_hash_activation_height: None,
         }
     }
 
@@ -105,7 +143,7 @@ impl EvolvePayloadBuilderConfig {
             config.contract_size_limit = extras.contract_size_limit;
             config.contract_size_limit_activation_height =
                 extras.contract_size_limit_activation_height;
-            config.hash_rewire_activation_height = extras.hash_rewire_activation_height;
+            config.canonical_hash_activation_height = extras.canonical_hash_activation_height;
         }
         Ok(config)
     }
@@ -160,14 +198,27 @@ impl EvolvePayloadBuilderConfig {
             .and_then(|(sink, activation)| (block_number >= activation).then_some(sink))
     }
 
-    /// Returns the configured hash rewire activation height if present.
-    pub const fn hash_rewire_settings(&self) -> Option<u64> {
-        self.hash_rewire_activation_height
-    }
-
-    /// Returns true if the canonical hash rewiring should be active for the provided block.
-    pub const fn is_hash_rewire_active_for_block(&self, block_number: u64) -> bool {
-        matches!(self.hash_rewire_activation_height, Some(activation) if block_number >= activation)
+    /// Returns true if canonical block hash validation should be enforced for the given block.
+    ///
+    /// This method controls whether the validator should reject blocks with hash mismatches
+    /// or bypass the check for legacy compatibility.
+    ///
+    /// # Returns
+    ///
+    /// - `true`: Enforce canonical hash validation (reject mismatches)
+    /// - `false`: Bypass hash validation (legacy mode for historical blocks)
+    ///
+    /// # Logic
+    ///
+    /// - If `canonical_hash_activation_height` is `None`: Always enforce (new networks)
+    /// - If `canonical_hash_activation_height` is `Some(N)`:
+    ///   - `block_number < N`: Don't enforce (legacy mode)
+    ///   - `block_number >= N`: Enforce (canonical mode)
+    pub const fn is_canonical_hash_enforced(&self, block_number: u64) -> bool {
+        match self.canonical_hash_activation_height {
+            Some(activation) => block_number >= activation,
+            None => true, // Default: enforce canonical hashes from genesis
+        }
     }
 }
 
@@ -247,8 +298,7 @@ mod tests {
             "baseFeeSink": sink,
             "baseFeeRedirectActivationHeight": 42,
             "mintAdmin": admin,
-            "mintPrecompileActivationHeight": 64,
-            "hashRewireActivationHeight": 128
+            "mintPrecompileActivationHeight": 64
         });
 
         let chainspec = create_test_chainspec_with_extras(Some(extras));
@@ -258,7 +308,6 @@ mod tests {
         assert_eq!(config.base_fee_redirect_activation_height, Some(42));
         assert_eq!(config.mint_admin, Some(admin));
         assert_eq!(config.mint_precompile_activation_height, Some(64));
-        assert_eq!(config.hash_rewire_activation_height, Some(128));
     }
 
     #[test]
@@ -284,7 +333,6 @@ mod tests {
 
         assert_eq!(config.base_fee_sink, None);
         assert_eq!(config.base_fee_redirect_activation_height, None);
-        assert_eq!(config.hash_rewire_activation_height, None);
     }
 
     #[test]
@@ -297,7 +345,6 @@ mod tests {
         assert_eq!(config.mint_admin, None);
         assert_eq!(config.base_fee_redirect_activation_height, None);
         assert_eq!(config.mint_precompile_activation_height, None);
-        assert_eq!(config.hash_rewire_activation_height, None);
     }
 
     #[test]
@@ -336,7 +383,6 @@ mod tests {
         assert_eq!(config.mint_admin, None);
         assert_eq!(config.base_fee_redirect_activation_height, None);
         assert_eq!(config.mint_precompile_activation_height, None);
-        assert_eq!(config.hash_rewire_activation_height, None);
     }
 
     #[test]
@@ -348,7 +394,6 @@ mod tests {
         assert_eq!(config.base_fee_redirect_activation_height, None);
         assert_eq!(config.mint_precompile_activation_height, None);
         assert_eq!(config.contract_size_limit, None);
-        assert_eq!(config.hash_rewire_activation_height, None);
     }
 
     #[test]
@@ -364,7 +409,7 @@ mod tests {
             mint_precompile_activation_height: Some(0),
             contract_size_limit: None,
             contract_size_limit_activation_height: None,
-            hash_rewire_activation_height: None,
+            canonical_hash_activation_height: None,
         };
         assert!(config_with_sink.validate().is_ok());
     }
@@ -379,7 +424,7 @@ mod tests {
             mint_precompile_activation_height: None,
             contract_size_limit: None,
             contract_size_limit_activation_height: None,
-            hash_rewire_activation_height: None,
+            canonical_hash_activation_height: None,
         };
 
         assert_eq!(config.base_fee_sink_for_block(4), None);
@@ -407,13 +452,11 @@ mod tests {
             config.mint_admin,
             Some(address!("00000000000000000000000000000000000000aa"))
         );
-        assert_eq!(config.hash_rewire_activation_height, None);
 
         let json_without_sink = json!({});
         let config: ChainspecEvolveConfig = serde_json::from_value(json_without_sink).unwrap();
         assert_eq!(config.base_fee_sink, None);
         assert_eq!(config.mint_admin, None);
-        assert_eq!(config.hash_rewire_activation_height, None);
     }
 
     #[test]
@@ -513,16 +556,28 @@ mod tests {
     }
 
     #[test]
-    fn test_hash_rewire_activation_height_parsed() {
+    fn test_canonical_hash_activation_from_chainspec() {
         let extras = json!({
-            "hashRewireActivationHeight": 500
+            "canonicalHashActivationHeight": 500
         });
 
         let chainspec = create_test_chainspec_with_extras(Some(extras));
         let config = EvolvePayloadBuilderConfig::from_chain_spec(&chainspec).unwrap();
 
-        assert_eq!(config.hash_rewire_activation_height, Some(500));
-        assert!(config.is_hash_rewire_active_for_block(600));
-        assert!(!config.is_hash_rewire_active_for_block(400));
+        assert_eq!(config.canonical_hash_activation_height, Some(500));
+        // Before activation: legacy mode (not enforced)
+        assert!(!config.is_canonical_hash_enforced(499));
+        // At and after activation: canonical mode (enforced)
+        assert!(config.is_canonical_hash_enforced(500));
+        assert!(config.is_canonical_hash_enforced(600));
+    }
+
+    #[test]
+    fn test_canonical_hash_default_enforces_from_genesis() {
+        // When not configured, canonical hashes should be enforced from genesis
+        let config = EvolvePayloadBuilderConfig::new();
+        assert_eq!(config.canonical_hash_activation_height, None);
+        assert!(config.is_canonical_hash_enforced(0));
+        assert!(config.is_canonical_hash_enforced(1000));
     }
 }

crates/node/src/validator.rs

@@ -25,6 +25,17 @@ use crate::{
 };
 
 /// Evolve engine validator that handles custom payload validation.
+///
+/// This validator extends the standard Ethereum payload validation with support for
+/// legacy block hash compatibility. See [`EvolvePayloadBuilderConfig::canonical_hash_activation_height`]
+/// for details on the migration strategy.
+///
+/// # Block Hash Validation
+///
+/// Early versions of ev-node passed block hashes from height H-1 instead of H,
+/// causing block explorers (e.g., Blockscout) to show all blocks as forks. This
+/// validator can bypass hash mismatch errors for historical blocks while enforcing
+/// canonical validation for new blocks, controlled by `canonical_hash_activation_height`.
 #[derive(Debug, Clone)]
 pub struct EvolveEngineValidator {
     inner: EthereumExecutionPayloadValidator<ChainSpec>,
@@ -56,7 +67,6 @@ impl PayloadValidator<EvolveEngineTypes> for EvolveEngineValidator {
     ) -> Result<RecoveredBlock<Self::Block>, NewPayloadError> {
         info!("Evolve engine validator: validating payload");
 
-        // Use inner validator but with custom evolve handling.
         match self.inner.ensure_well_formed_payload(payload.clone()) {
             Ok(sealed_block) => {
                 info!("Evolve engine validator: payload validation succeeded");
@@ -65,29 +75,44 @@ impl PayloadValidator<EvolveEngineTypes> for EvolveEngineValidator {
                     .map_err(|e| NewPayloadError::Other(e.into()))
             }
             Err(err) => {
-                // Log the error for debugging.
                 tracing::debug!("Evolve payload validation error: {:?}", err);
 
-                // Check if this is a block hash mismatch error - bypass it for evolve.
+                // Handle block hash mismatch errors specially for legacy compatibility.
+                //
+                // Background: Early versions of ev-node passed block hashes from height H-1
+                // instead of H when communicating with ev-reth via the Engine API. This caused
+                // block hashes to not match the canonical Ethereum block hash (keccak256 of
+                // RLP-encoded header), resulting in block explorers like Blockscout incorrectly
+                // displaying every block as a fork due to parent hash mismatches.
+                //
+                // For existing networks with historical blocks containing these non-canonical
+                // hashes, we need to bypass this validation to allow nodes to sync from genesis.
+                // The `canonical_hash_activation_height` config controls when to start enforcing
+                // canonical hashes for new blocks.
                 if matches!(err, alloy_rpc_types::engine::PayloadError::BlockHash { .. }) {
                     let block_number = payload.payload.block_number();
-                    if self.config.is_hash_rewire_active_for_block(block_number) {
+
+                    // If canonical hash enforcement is active for this block, reject the mismatch
+                    if self.config.is_canonical_hash_enforced(block_number) {
                         tracing::warn!(
                             block_number,
-                            "canonical hash rewiring active; rejecting mismatched block hash"
+                            "canonical hash enforcement active; rejecting mismatched block hash"
                         );
                         return Err(NewPayloadError::Eth(err));
                     }
 
-                    info!("Evolve engine validator: bypassing block hash mismatch for ev-reth");
-                    // For evolve, we trust the payload builder - just parse the block without hash validation.
+                    // Legacy mode: bypass hash mismatch to allow syncing historical blocks.
+                    // Re-seal the block with the correct canonical hash (keccak256 of header).
+                    info!(
+                        block_number,
+                        "bypassing block hash mismatch (legacy mode before activation height)"
+                    );
                     let ExecutionData { payload, sidecar } = payload;
                     let sealed_block = payload.try_into_block_with_sidecar(&sidecar)?.seal_slow();
                     sealed_block
                         .try_recover()
                         .map_err(|e| NewPayloadError::Other(e.into()))
                 } else {
-                    // For other errors, re-throw them.
                     Err(NewPayloadError::Eth(err))
                 }
             }
@@ -168,10 +193,10 @@ mod tests {
     use reth_chainspec::ChainSpecBuilder;
     use reth_primitives::{Block, SealedBlock};
 
-    fn validator_with_activation(height: Option<u64>) -> EvolveEngineValidator {
+    fn validator_with_activation(activation_height: Option<u64>) -> EvolveEngineValidator {
         let chain_spec = Arc::new(ChainSpecBuilder::mainnet().build());
         let mut config = EvolvePayloadBuilderConfig::new();
-        config.hash_rewire_activation_height = height;
+        config.canonical_hash_activation_height = activation_height;
         EvolveEngineValidator::new(chain_spec, config)
     }
 
@@ -185,17 +210,19 @@ mod tests {
     }
 
     #[test]
-    fn legacy_bypass_allows_mismatch_before_activation() {
-        let validator = validator_with_activation(None);
+    fn test_legacy_mode_bypasses_hash_mismatch() {
+        // When activation height is set in the future, legacy mode should bypass hash mismatches
+        let validator = validator_with_activation(Some(1000));
         let payload = mismatched_payload();
 
         validator
             .ensure_well_formed_payload(payload)
-            .expect("hash mismatch should be bypassed before activation");
+            .expect("hash mismatch should be bypassed in legacy mode");
     }
 
     #[test]
-    fn canonical_mode_rejects_mismatch_after_activation() {
+    fn test_canonical_mode_rejects_hash_mismatch() {
+        // When activation height is 0 (or in the past), canonical mode should reject mismatches
         let validator = validator_with_activation(Some(0));
         let payload = mismatched_payload();
 
@@ -207,4 +234,19 @@ mod tests {
             ))
         ));
     }
+
+    #[test]
+    fn test_default_enforces_canonical_hash() {
+        // When no activation height is set, canonical validation should be enforced (default)
+        let validator = validator_with_activation(None);
+        let payload = mismatched_payload();
+
+        let result = validator.ensure_well_formed_payload(payload);
+        assert!(matches!(
+            result,
+            Err(NewPayloadError::Eth(
+                alloy_rpc_types::engine::PayloadError::BlockHash { .. }
+            ))
+        ));
+    }
 }