feat(engine): Update execution cache on inserted executed blocks (#19822)

Co-authored-by: Matthias Seitz <[email protected]>

Author: 0x00101010

crates/engine/tree/src/tree/mod.rs

@@ -1374,6 +1374,7 @@ where
                         }
 
                         self.state.tree_state.insert_executed(block.clone());
+                        self.payload_validator.on_inserted_executed_block(block.clone());
                         self.metrics.engine.inserted_already_executed_blocks.increment(1);
                         self.emit_event(EngineApiEvent::BeaconConsensus(
                             ConsensusEngineEvent::CanonicalBlockAdded(block, now.elapsed()),

crates/engine/tree/src/tree/payload_processor/mod.rs

@@ -13,6 +13,7 @@ use crate::tree::{
     sparse_trie::SparseTrieTask,
     StateProviderBuilder, TreeConfig,
 };
+use alloy_eips::eip1898::BlockWithParent;
 use alloy_evm::{block::StateChangeSource, ToTxEnv};
 use alloy_primitives::B256;
 use crossbeam_channel::Sender as CrossbeamSender;
@@ -464,6 +465,54 @@ where
             cleared_sparse_trie.lock().replace(cleared_trie);
         });
     }
+
+    /// Updates the execution cache with the post-execution state from an inserted block.
+    ///
+    /// This is used when blocks are inserted directly (e.g., locally built blocks by sequencers)
+    /// to ensure the cache remains warm for subsequent block execution.
+    ///
+    /// The cache enables subsequent blocks to reuse account, storage, and bytecode data without
+    /// hitting the database, maintaining performance consistency.
+    pub(crate) fn on_inserted_executed_block(
+        &self,
+        block_with_parent: BlockWithParent,
+        bundle_state: &BundleState,
+    ) {
+        self.execution_cache.update_with_guard(|cached| {
+            if cached.as_ref().is_some_and(|c| c.executed_block_hash() != block_with_parent.parent) {
+                debug!(
+                    target: "engine::caching",
+                    parent_hash = %block_with_parent.parent,
+                    "Cannot find cache for parent hash, skip updating cache with new state for inserted executed block",
+                );
+                return;
+            }
+
+            // Take existing cache (if any) or create fresh caches
+            let (caches, cache_metrics) = match cached.take() {
+                Some(existing) => {
+                    existing.split()
+                }
+                None => (
+                    ExecutionCacheBuilder::default().build_caches(self.cross_block_cache_size),
+                    CachedStateMetrics::zeroed(),
+                ),
+            };
+
+            // Insert the block's bundle state into cache
+            let new_cache = SavedCache::new(block_with_parent.block.hash, caches, cache_metrics);
+            if new_cache.cache().insert_state(bundle_state).is_err() {
+                *cached = None;
+                debug!(target: "engine::caching", "cleared execution cache on update error");
+                return;
+            }
+            new_cache.update_metrics();
+
+            // Replace with the updated cache
+            *cached = Some(new_cache);
+            debug!(target: "engine::caching", ?block_with_parent, "Updated execution cache for inserted block");
+        });
+    }
 }
 
 /// Handle to all the spawned tasks.
@@ -703,6 +752,7 @@ mod tests {
         precompile_cache::PrecompileCacheMap,
         StateProviderBuilder, TreeConfig,
     };
+    use alloy_eips::eip1898::{BlockNumHash, BlockWithParent};
     use alloy_evm::block::StateChangeSource;
     use rand::Rng;
     use reth_chainspec::ChainSpec;
@@ -716,6 +766,7 @@ mod tests {
         test_utils::create_test_provider_factory_with_chain_spec,
         ChainSpecProvider, HashingWriter,
     };
+    use reth_revm::db::BundleState;
     use reth_testing_utils::generators;
     use reth_trie::{test_utils::state_root, HashedPostState};
     use revm_primitives::{Address, HashMap, B256, KECCAK_EMPTY, U256};
@@ -793,6 +844,70 @@ mod tests {
         assert!(new_checkout.is_some(), "new checkout should succeed after release and update");
     }
 
+    #[test]
+    fn on_inserted_executed_block_populates_cache() {
+        let payload_processor = PayloadProcessor::new(
+            WorkloadExecutor::default(),
+            EthEvmConfig::new(Arc::new(ChainSpec::default())),
+            &TreeConfig::default(),
+            PrecompileCacheMap::default(),
+        );
+
+        let parent_hash = B256::from([1u8; 32]);
+        let block_hash = B256::from([10u8; 32]);
+        let block_with_parent = BlockWithParent {
+            block: BlockNumHash { hash: block_hash, number: 1 },
+            parent: parent_hash,
+        };
+        let bundle_state = BundleState::default();
+
+        // Cache should be empty initially
+        assert!(payload_processor.execution_cache.get_cache_for(block_hash).is_none());
+
+        // Update cache with inserted block
+        payload_processor.on_inserted_executed_block(block_with_parent, &bundle_state);
+
+        // Cache should now exist for the block hash
+        let cached = payload_processor.execution_cache.get_cache_for(block_hash);
+        assert!(cached.is_some());
+        assert_eq!(cached.unwrap().executed_block_hash(), block_hash);
+    }
+
+    #[test]
+    fn on_inserted_executed_block_skips_on_parent_mismatch() {
+        let payload_processor = PayloadProcessor::new(
+            WorkloadExecutor::default(),
+            EthEvmConfig::new(Arc::new(ChainSpec::default())),
+            &TreeConfig::default(),
+            PrecompileCacheMap::default(),
+        );
+
+        // Setup: populate cache with block 1
+        let block1_hash = B256::from([1u8; 32]);
+        payload_processor
+            .execution_cache
+            .update_with_guard(|slot| *slot = Some(make_saved_cache(block1_hash)));
+
+        // Try to insert block 3 with wrong parent (should skip and keep block 1's cache)
+        let wrong_parent = B256::from([99u8; 32]);
+        let block3_hash = B256::from([3u8; 32]);
+        let block_with_parent = BlockWithParent {
+            block: BlockNumHash { hash: block3_hash, number: 3 },
+            parent: wrong_parent,
+        };
+        let bundle_state = BundleState::default();
+
+        payload_processor.on_inserted_executed_block(block_with_parent, &bundle_state);
+
+        // Cache should still be for block 1 (unchanged)
+        let cached = payload_processor.execution_cache.get_cache_for(block1_hash);
+        assert!(cached.is_some(), "Original cache should be preserved");
+
+        // Cache for block 3 should not exist
+        let cached3 = payload_processor.execution_cache.get_cache_for(block3_hash);
+        assert!(cached3.is_none(), "New block cache should not be created on mismatch");
+    }
+
     fn create_mock_state_updates(num_accounts: usize, updates_per_account: usize) -> Vec<EvmState> {
         let mut rng = generators::rng();
         let all_addresses: Vec<Address> = (0..num_accounts).map(|_| rng.random()).collect();

crates/engine/tree/src/tree/payload_validator.rs

@@ -1115,6 +1115,12 @@ pub trait EngineValidator<
         block: RecoveredBlock<N::Block>,
         ctx: TreeCtx<'_, N>,
     ) -> ValidationOutcome<N>;
+
+    /// Hook called after an executed block is inserted directly into the tree.
+    ///
+    /// This is invoked when blocks are inserted via `InsertExecutedBlock` (e.g., locally built
+    /// blocks by sequencers) to allow implementations to update internal state such as caches.
+    fn on_inserted_executed_block(&self, block: ExecutedBlock<N>);
 }
 
 impl<N, Types, P, Evm, V> EngineValidator<Types> for BasicEngineValidator<P, Evm, V>
@@ -1163,6 +1169,13 @@ where
     ) -> ValidationOutcome<N> {
         self.validate_block_with_state(BlockOrPayload::Block(block), ctx)
     }
+
+    fn on_inserted_executed_block(&self, block: ExecutedBlock<N>) {
+        self.payload_processor.on_inserted_executed_block(
+            block.recovered_block.block_with_parent(),
+            block.execution_output.state(),
+        );
+    }
 }
 
 /// Enum representing either block or payload being validated.