use the correct hash

Author: tac0turtle

README.md

@@ -456,3 +456,24 @@ This project builds upon the excellent work of:
 
 - [Reth](https://github.com/paradigmxyz/reth) - The Rust Ethereum client
 - [Evolve](https://ev.xyz/) - The modular rollup framework
+
+### Canonical Block Hash Activation
+
+Legacy deployments allowed application-level hashes to flow through the Engine API, which meant
+Reth had to ignore block-hash mismatches and upstream tooling flagged every block as a fork. Newer
+networks can opt-in to canonical keccak block hashes by setting `hashRewireActivationHeight` inside
+the `evolve` section of the chainspec:
+
+```json
+"config": {
+  ...,
+  "evolve": {
+    "hashRewireActivationHeight": 0
+  }
+}
+```
+
+Set the activation height to the first block where canonical hashes should be enforced (use `0` for
+fresh networks). Before the activation height the node continues to bypass hash mismatches so
+existing chains keep working; after activation, the node rejects malformed payloads and the reported
+block hash always matches the standard Engine API expectations.

crates/node/src/builder.rs

@@ -187,7 +187,13 @@ where
             .finish(&state_provider)
             .map_err(PayloadBuilderError::other)?;
 
-        let sealed_block = block.sealed_block().clone();
+        let mut sealed_block = block.sealed_block().clone();
+
+        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);
+        }
 
         tracing::info!(
                     block_number = sealed_block.number,

crates/node/src/config.rs

@@ -21,6 +21,9 @@ 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>,
 }
 
 /// Configuration for the Evolve payload builder
@@ -44,6 +47,9 @@ 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.
+    #[serde(default)]
+    pub hash_rewire_activation_height: Option<u64>,
 }
 
 impl EvolvePayloadBuilderConfig {
@@ -56,6 +62,7 @@ impl EvolvePayloadBuilderConfig {
             mint_precompile_activation_height: None,
             contract_size_limit: None,
             contract_size_limit_activation_height: None,
+            hash_rewire_activation_height: None,
         }
     }
 
@@ -90,6 +97,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;
         }
         Ok(config)
     }
@@ -143,6 +151,16 @@ impl EvolvePayloadBuilderConfig {
         self.base_fee_redirect_settings()
             .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)
+    }
 }
 
 /// Errors that can occur during configuration validation
@@ -221,7 +239,8 @@ mod tests {
             "baseFeeSink": sink,
             "baseFeeRedirectActivationHeight": 42,
             "mintAdmin": admin,
-            "mintPrecompileActivationHeight": 64
+            "mintPrecompileActivationHeight": 64,
+            "hashRewireActivationHeight": 128
         });
 
         let chainspec = create_test_chainspec_with_extras(Some(extras));
@@ -231,6 +250,7 @@ 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]
@@ -256,6 +276,7 @@ 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]
@@ -268,6 +289,7 @@ 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]
@@ -306,6 +328,7 @@ 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]
@@ -317,6 +340,7 @@ 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]
@@ -332,6 +356,7 @@ mod tests {
             mint_precompile_activation_height: Some(0),
             contract_size_limit: None,
             contract_size_limit_activation_height: None,
+            hash_rewire_activation_height: None,
         };
         assert!(config_with_sink.validate().is_ok());
     }
@@ -346,6 +371,7 @@ mod tests {
             mint_precompile_activation_height: None,
             contract_size_limit: None,
             contract_size_limit_activation_height: None,
+            hash_rewire_activation_height: None,
         };
 
         assert_eq!(config.base_fee_sink_for_block(4), None);
@@ -373,11 +399,13 @@ 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]
@@ -475,4 +503,18 @@ mod tests {
             DEFAULT_CONTRACT_SIZE_LIMIT
         );
     }
+
+    #[test]
+    fn test_hash_rewire_activation_height_parsed() {
+        let extras = json!({
+            "hashRewireActivationHeight": 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));
+    }
 }

crates/node/src/validator.rs

@@ -19,19 +19,24 @@ use reth_ethereum_payload_builder::EthereumExecutionPayloadValidator;
 use reth_primitives_traits::{Block as _, RecoveredBlock};
 use tracing::info;
 
-use crate::{attributes::EvolveEnginePayloadAttributes, node::EvolveEngineTypes};
+use crate::{
+    attributes::EvolveEnginePayloadAttributes, config::EvolvePayloadBuilderConfig,
+    node::EvolveEngineTypes,
+};
 
 /// Evolve engine validator that handles custom payload validation.
 #[derive(Debug, Clone)]
 pub struct EvolveEngineValidator {
     inner: EthereumExecutionPayloadValidator<ChainSpec>,
+    config: EvolvePayloadBuilderConfig,
 }
 
 impl EvolveEngineValidator {
     /// Instantiates a new validator.
-    pub const fn new(chain_spec: Arc<ChainSpec>) -> Self {
+    pub const fn new(chain_spec: Arc<ChainSpec>, config: EvolvePayloadBuilderConfig) -> Self {
         Self {
             inner: EthereumExecutionPayloadValidator::new(chain_spec),
+            config,
         }
     }
 
@@ -65,6 +70,15 @@ impl PayloadValidator<EvolveEngineTypes> for EvolveEngineValidator {
 
                 // Check if this is a block hash mismatch error - bypass it for evolve.
                 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) {
+                        tracing::warn!(
+                            block_number,
+                            "canonical hash rewiring 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.
                     let ExecutionData { payload, sidecar } = payload;
@@ -142,6 +156,55 @@ where
     type Validator = EvolveEngineValidator;
 
     async fn build(self, ctx: &AddOnsContext<'_, N>) -> eyre::Result<Self::Validator> {
-        Ok(EvolveEngineValidator::new(ctx.config.chain.clone()))
+        let config = EvolvePayloadBuilderConfig::from_chain_spec(ctx.config.chain.as_ref())?;
+        Ok(EvolveEngineValidator::new(ctx.config.chain.clone(), config))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use alloy_primitives::B256;
+    use reth_chainspec::ChainSpecBuilder;
+    use reth_primitives::{Block, SealedBlock};
+
+    fn validator_with_activation(height: Option<u64>) -> EvolveEngineValidator {
+        let chain_spec = Arc::new(ChainSpecBuilder::mainnet().build());
+        let mut config = EvolvePayloadBuilderConfig::new();
+        config.hash_rewire_activation_height = height;
+        EvolveEngineValidator::new(chain_spec, config)
+    }
+
+    fn mismatched_payload() -> ExecutionData {
+        let sealed_block: SealedBlock<Block> = SealedBlock::default();
+        let block_hash = sealed_block.hash();
+        let block = sealed_block.into_block();
+        let mut data = ExecutionData::from_block_unchecked(block_hash, &block);
+        data.payload.as_v1_mut().block_hash = B256::repeat_byte(0x42);
+        data
+    }
+
+    #[test]
+    fn legacy_bypass_allows_mismatch_before_activation() {
+        let validator = validator_with_activation(None);
+        let payload = mismatched_payload();
+
+        validator
+            .ensure_well_formed_payload(payload)
+            .expect("hash mismatch should be bypassed before activation");
+    }
+
+    #[test]
+    fn canonical_mode_rejects_mismatch_after_activation() {
+        let validator = validator_with_activation(Some(0));
+        let payload = mismatched_payload();
+
+        let result = validator.ensure_well_formed_payload(payload);
+        assert!(matches!(
+            result,
+            Err(NewPayloadError::Eth(
+                alloy_rpc_types::engine::PayloadError::BlockHash { .. }
+            ))
+        ));
     }
 }

docs/canonical-hash-plan.md

@@ -0,0 +1,47 @@
+# Plan: Restore Canonical Block Hashes While Preserving Rollkit Apphash
+
+## Goals
+
+- Emit keccak-based canonical hashes inside every header so upstream Reth tooling no longer reports continuous forks.
+- Preserve the Rollkit `apphash` in a discoverable location so DA clients continue to verify block linkage.
+- Gate the change behind a chainspec activation height for deterministic rollouts.
+
+## 1. Payload Builder & Types
+
+- Update `EvolvePayloadBuilder` (`crates/node/src/builder.rs`) to compute the keccak hash after `builder.finish` and assign it to `header.hash`/`parent_hash` before sealing.
+- Extend `EvolveEnginePayloadAttributes` and related types (`crates/evolve/src/types.rs`, `crates/node/src/attributes.rs`) to carry the incoming `apphash` separately from the canonical hash.
+- Persist the `apphash` to a new header field (candidate: encode in `extra_data` or define a dedicated header extension struct shared across payload serialization).
+- Introduce activation-aware logic: pre-activation blocks keep legacy behavior; post-activation blocks always write canonical hashes while still storing the `apphash` in the new location.
+
+## 2. Validator & Consensus
+
+- Modify `EvolveEngineValidator` (`crates/node/src/validator.rs`) to stop bypassing `PayloadError::BlockHashMismatch` after the activation height. Retain the bypass for legacy blocks.
+- Ensure `EvolveConsensus` (`crates/evolve/src/consensus.rs`) now validates hash/parentHash linkages post-activation while keeping the relaxed timestamp rule.
+- Audit any code paths that rely on the `apphash` (e.g., Rollkit-specific checks) and point them to the relocated field.
+
+## 3. RPC & Serialization
+
+- Adjust the conversion helpers that produce `ExecutionPayload` / `ExecutionPayloadEnvelope` values so RPC consumers see the canonical hash in the standard field and the `apphash` via either `extraData` or a new optional field.
+- Clearly document the new field semantics so explorers/light clients know where to read the Rollkit hash.
+- Maintain backward compatibility in request parsing: continue accepting payload attributes that include the `apphash`, even though it is no longer stored in `header.hash`.
+
+## 4. Chainspec & Configuration
+
+- Add a new evolve config flag, e.g. `hashRewireActivationHeight`, parsed in `crates/evolve/src/config.rs` and surfaced through `EvolvePayloadBuilderConfig`.
+- Validate the flag alongside existing evolve settings; log or reject invalid configurations.
+- Update sample configs (`etc/ev-reth-genesis.json`) and the README/upgrade docs with instructions for setting the activation height.
+
+## 5. Testing & Tooling
+
+- Extend e2e tests (`crates/tests/src/e2e_tests.rs`, `test_evolve_engine_api.rs`) to cover both pre- and post-activation behavior, asserting that:
+  - Legacy mode still bypasses hash mismatches.
+  - Post-activation blocks produce canonical parent links and expose the `apphash` in the new field.
+- Add unit tests around the serialization helpers to ensure RPC payloads echo both hashes correctly.
+- Verify Rollkit integration tests continue to pass once they read the `apphash` from the new location.
+
+## 6. Rollout Steps
+
+1. Implement the code changes behind the activation height flag and land them with comprehensive tests.
+2. Publish an upgrade note describing the new flag, how to set the activation block, and how to verify the behavior via RPC.
+3. Coordinate with testnet/mainnet operators to schedule the activation block and ensure explorers/monitoring tools understand the relocated `apphash` field.
+4. After activation, monitor forkchoice health and Rollkit ingestion to confirm both canonical and DA workflows function correctly.