more docs

Author: tac0turtle

CHANGELOG.md

@@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Fixed
 - Add missing payload attribute extraction in `EvolvePayloadBuilder` to properly handle transactions submitted via Engine API ([#33](https://github.com/evstack/ev-reth/pull/33))
 - Remove unused configuration parameters to clean up codebase ([#32](https://github.com/evstack/ev-reth/pull/32))
+- Ensure `stateRoot` follows Ethereum post-state semantics to avoid false fork reports caused by height-1 root mismatches
 
 ### Changed
 - Use `best_transactions` instead of `pending_transactions` queue for improved transaction selection logic ([#29](https://github.com/evstack/ev-reth/pull/29))

README.md

@@ -464,6 +464,12 @@ Reth had to ignore block-hash mismatches and upstream tooling flagged every bloc
 networks can opt-in to canonical keccak block hashes by setting `hashRewireActivationHeight` inside
 the `evolve` section of the chainspec:
 
+Separately, Ethereum clients expect `stateRoot` to be the current block's post-state root (after
+executing this block's transactions on top of the parent). If an integration accidentally supplies
+the parent (height-1) root instead, execution clients can report persistent "forks" that are really
+just state-root mismatches. ev-reth computes and exposes the canonical post-state root so state-root
+validation behaves like standard Ethereum.
+
 ```json
 "config": {
   ...,

crates/node/src/builder.rs

@@ -177,7 +177,12 @@ where
             }
         }
 
-        // Finish building the block - this calculates the proper state root
+        // Finish building the block. This computes the *current block's* post-state root.
+        //
+        // Ethereum clients expect `header.state_root` to equal the post-state after executing the
+        // transactions in this block on top of the parent state. Accidentally using the parent
+        // (height-1) state root here can make downstream execution clients think each block is on
+        // a different fork, even when the chain is otherwise canonical.
         let BlockBuilderOutcome {
             execution_result: _,
             hashed_state: _,
@@ -189,6 +194,9 @@ where
 
         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();

crates/node/src/config.rs

@@ -48,6 +48,14 @@ pub struct EvolvePayloadBuilderConfig {
     #[serde(default)]
     pub contract_size_limit_activation_height: Option<u64>,
     /// Block height at which canonical hash rewiring activates.
+    ///
+    /// 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.
+    ///
+    /// 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.
     #[serde(default)]
     pub hash_rewire_activation_height: Option<u64>,
 }