Skip to main content

reth_provider/providers/
blockchain_provider.rs

1use crate::{
2    providers::{
3        ConsistentProvider, ProviderNodeTypes, RocksDBProvider, StaticFileProvider,
4        StaticFileProviderRWRefMut,
5    },
6    AccountReader, BalProvider, BalStoreHandle, BlockHashReader, BlockIdReader, BlockNumReader,
7    BlockReader, BlockReaderIdExt, BlockSource, CanonChainTracker, CanonStateNotifications,
8    CanonStateSubscriptions, ChainSpecProvider, ChainStateBlockReader, ChangeSetReader,
9    DatabaseProviderFactory, HeaderProvider, MetadataProvider, ProviderError, ProviderFactory,
10    PruneCheckpointReader, ReceiptProvider, ReceiptProviderIdExt, RocksDBProviderFactory,
11    StageCheckpointReader, StateProvider, StateProviderBox, StateProviderFactory, StateReader,
12    StaticFileProviderFactory, TransactionVariant, TransactionsProvider,
13};
14use alloy_consensus::{transaction::TransactionMeta, BlockHeader};
15use alloy_eips::{BlockHashOrNumber, BlockId, BlockNumHash, BlockNumberOrTag};
16use alloy_primitives::{Address, BlockHash, BlockNumber, Bytes, TxHash, TxNumber, B256};
17use alloy_rpc_types_engine::ForkchoiceState;
18use reth_chain_state::{
19    BlockState, CanonicalInMemoryState, CanonicalInMemoryStateWriter, ChainInfoHeaders,
20    ExecutedBlock, ForkChoiceNotifications, ForkChoiceSubscriptions, PersistedBlockNotifications,
21    PersistedBlockSubscriptions,
22};
23use reth_chainspec::ChainInfo;
24use reth_db_api::models::{AccountBeforeTx, BlockNumberAddress, StoredBlockBodyIndices};
25use reth_execution_types::{ExecutionOutcome, RecoveredBlockAndExecutionOutput};
26use reth_node_types::{BlockTy, HeaderTy, NodeTypes, NodeTypesWithDB, ReceiptTy, TxTy};
27use reth_primitives_traits::{
28    Account, RecoveredBlock, SealedHeader, SealedOrRecoveredBlock, StorageEntry,
29};
30use reth_prune_types::{PruneCheckpoint, PruneSegment};
31use reth_stages_types::{StageCheckpoint, StageId};
32use reth_static_file_types::StaticFileSegment;
33use reth_storage_api::{
34    BlockBodyIndicesProvider, DatabaseProviderROFactory, GetBlockAccessListLimit,
35    NodePrimitivesProvider, RangeEnd, RangeResponse, RangeResult, StateRangeProvider,
36    StateRangeProviderFactory, StateRangeView, StorageChangeSetReader, StorageRangeResult,
37};
38use reth_storage_errors::provider::ProviderResult;
39use reth_storage_overlay::{OverlayStateProvider, OverlayStateProviderFactory, OwnedProvider};
40use reth_trie::{
41    hashed_cursor::{HashedCursor, HashedCursorFactory},
42    metrics::TrieRootMetrics,
43    proof::{Proof, StorageProof},
44    MultiProofTargets, StorageRoot, TrieType,
45};
46use std::{
47    ops::{RangeBounds, RangeInclusive},
48    sync::Arc,
49    time::Instant,
50};
51use tracing::trace;
52
53/// Number of most-recent blocks whose state roots remain resolvable via
54/// [`StateRangeProviderFactory::state_range_provider`].
55pub const SNAPSHOT_STATE_RETENTION: u64 = 128;
56
57type StateRangeDbProvider<N> = <ProviderFactory<N> as DatabaseProviderFactory>::Provider;
58type HistoricalStateRangeProvider<N> =
59    OverlayStateProvider<OwnedProvider<StateRangeDbProvider<N>>, <N as NodeTypes>::Primitives>;
60
61/// The main type for interacting with the blockchain.
62///
63/// This type serves as the main entry point for interacting with the blockchain and provides data
64/// from database storage and from the blockchain tree (pending state etc.) It is a simple wrapper
65/// type that holds an instance of the database and the blockchain tree.
66#[derive(Debug)]
67pub struct BlockchainProvider<N: NodeTypesWithDB> {
68    /// Provider factory used to access the database.
69    pub(crate) database: ProviderFactory<N>,
70    /// Tracks the chain info wrt forkchoice updates and in memory canonical
71    /// state.
72    pub(crate) canonical_in_memory_state: CanonicalInMemoryState<N::Primitives>,
73    /// Store for BALs associated with this provider view.
74    pub(crate) bal_store: BalStoreHandle,
75}
76
77impl<N: NodeTypesWithDB> Clone for BlockchainProvider<N> {
78    fn clone(&self) -> Self {
79        Self {
80            database: self.database.clone(),
81            canonical_in_memory_state: self.canonical_in_memory_state.clone(),
82            bal_store: self.bal_store.clone(),
83        }
84    }
85}
86
87impl<N: ProviderNodeTypes> BlockchainProvider<N> {
88    /// Creates a provider like [`Self::new_with_writer`], without the writer of its canonical
89    /// in-memory state.
90    pub fn new(storage: ProviderFactory<N>) -> ProviderResult<Self> {
91        Self::new_with_writer(storage).map(|(provider, _)| provider)
92    }
93
94    /// Creates a provider over `storage` and the in-memory state of `storage`, fetching the
95    /// latest, safe and finalized headers from the database to initialize the provider, and
96    /// returns it with the writer of its canonical in-memory state.
97    ///
98    /// The provider and its clones read that state, and the writer is for the engine that changes
99    /// it.
100    ///
101    /// The in-memory blocks are shared with every other handle of that in-memory state. The chain
102    /// info and the canonical state notifications belong to the returned provider and its clones.
103    pub fn new_with_writer(
104        storage: ProviderFactory<N>,
105    ) -> ProviderResult<(Self, CanonicalInMemoryStateWriter<N::Primitives>)> {
106        let provider = storage.provider()?;
107        let best = provider.chain_info()?;
108        let latest = provider
109            .header_by_number(best.best_number)?
110            .ok_or_else(|| ProviderError::HeaderNotFound(best.best_number.into()))?;
111        let finalized_header = provider
112            .last_finalized_block_number()?
113            .map(|num| provider.sealed_header(num))
114            .transpose()?
115            .flatten();
116        let safe_header = provider
117            .last_safe_block_number()?
118            .or_else(|| {
119                // for the purpose of this we can also use the finalized block if we don't have the
120                // safe block
121                provider.last_finalized_block_number().ok().flatten()
122            })
123            .map(|num| provider.sealed_header(num))
124            .transpose()?
125            .flatten();
126        let canonical_in_memory_state_writer = CanonicalInMemoryStateWriter::new(
127            ChainInfoHeaders {
128                canonical_head: SealedHeader::new(latest, best.best_hash),
129                safe: safe_header,
130                finalized: finalized_header,
131            },
132            storage.in_memory_state().clone(),
133        );
134        let canonical_in_memory_state =
135            canonical_in_memory_state_writer.canonical_in_memory_state().clone();
136        let bal_store = storage.bal_store().clone();
137
138        Ok((
139            Self { database: storage, canonical_in_memory_state, bal_store },
140            canonical_in_memory_state_writer,
141        ))
142    }
143
144    /// Gets a clone of `canonical_in_memory_state`.
145    pub fn canonical_in_memory_state(&self) -> CanonicalInMemoryState<N::Primitives> {
146        self.canonical_in_memory_state.clone()
147    }
148
149    /// Returns a provider with a created `DbTx` inside, which allows fetching data from the
150    /// database using different types of providers. Example: [`HeaderProvider`]
151    /// [`BlockHashReader`]. This may fail if the inner read database transaction fails to open.
152    #[track_caller]
153    pub fn consistent_provider(&self) -> ProviderResult<ConsistentProvider<N>> {
154        ConsistentProvider::new(self.database.clone(), self.canonical_in_memory_state())
155    }
156
157    /// Returns a state provider for the post-state of an already resolved in-memory chain.
158    ///
159    /// This is the post-state of `state.hash()`. Because the caller already holds the in-memory
160    /// chain, the overlay manager does not have to look it up again.
161    fn state_provider_for_state(
162        &self,
163        state: Arc<BlockState<N::Primitives>>,
164    ) -> ProviderResult<StateProviderBox> {
165        let state_provider_factory = OverlayStateProviderFactory::new(
166            self.database.clone(),
167            self.database.overlay_manager().overlay_builder_for_state(state),
168        );
169        Ok(Box::new(state_provider_factory.database_provider_ro()?))
170    }
171
172    /// Returns a historical state provider using an existing database snapshot.
173    ///
174    /// Callers such as RPC choose the block, so the trie reverts it accumulates stay out of the
175    /// changeset cache the engine shares.
176    pub fn state_provider_from_database(
177        &self,
178        provider: StateRangeDbProvider<N>,
179        block_hash: B256,
180    ) -> StateProviderBox {
181        Box::new(OverlayStateProvider::new(
182            provider,
183            self.database
184                .overlay_manager()
185                .overlay_builder(block_hash)
186                .without_trie_revert_caching(),
187        ))
188    }
189
190    /// Returns the canonical in-memory block with `state_root`.
191    fn block_state_by_root(&self, state_root: B256) -> Option<Arc<BlockState<N::Primitives>>> {
192        self.canonical_in_memory_state
193            .canonical_chain()
194            .find(|state| state.state_root() == state_root)
195    }
196
197    /// Resolves `state_root` into a range view over `provider`'s snapshot, preferring
198    /// `block_state` over the persisted-history fallback.
199    ///
200    /// The snap attempt is read from `provider` too, so a bootstrap committing after the snapshot
201    /// was taken can't slip its downloads past the check.
202    fn state_range_view(
203        &self,
204        provider: StateRangeDbProvider<N>,
205        block_state: Option<Arc<BlockState<N::Primitives>>>,
206        state_root: B256,
207    ) -> ProviderResult<Option<StateRangeView>> {
208        if provider.snap_attempt()?.is_some_and(|attempt| !attempt.is_verified()) {
209            return Ok(None)
210        }
211
212        // A pipeline run commits executed state before it moves `Finish`, so until then the state
213        // tables are ahead of every retained block.
214        let Some(finish) = provider.get_stage_checkpoint(StageId::Finish)? else { return Ok(None) };
215        if provider
216            .get_stage_checkpoint(StageId::Execution)?
217            .is_some_and(|execution| execution.block_number > finish.block_number)
218        {
219            return Ok(None)
220        }
221
222        let overlay_manager = self.database.overlay_manager();
223        let overlay_builder = match block_state {
224            Some(state) => overlay_manager.overlay_builder_for_state(state),
225            None => {
226                let Some(block_hash) =
227                    retained_block_hash::<N>(&provider, finish.block_number, state_root)?
228                else {
229                    return Ok(None)
230                };
231                overlay_manager.overlay_builder(block_hash)
232            }
233        };
234
235        // Peers choose the root, so its reverts stay out of the cache the engine shares.
236        Ok(Some(Box::new(HistoricalStateRangeView {
237            provider: OverlayStateProvider::new(
238                provider,
239                overlay_builder.without_trie_revert_caching(),
240            ),
241        })))
242    }
243}
244
245impl<N: NodeTypesWithDB> NodePrimitivesProvider for BlockchainProvider<N> {
246    type Primitives = N::Primitives;
247}
248
249impl<N: ProviderNodeTypes> BalProvider for BlockchainProvider<N> {
250    fn bal_store(&self) -> &BalStoreHandle {
251        &self.bal_store
252    }
253
254    fn get_bal_by_hash(&self, block_hash: BlockHash) -> ProviderResult<Option<Bytes>> {
255        Ok(self.get_bals_by_hashes(&[block_hash])?.pop().flatten())
256    }
257
258    fn get_bals_by_hashes(&self, block_hashes: &[BlockHash]) -> ProviderResult<Vec<Option<Bytes>>> {
259        self.get_bals_by_hashes_with_limit(block_hashes, GetBlockAccessListLimit::None)
260    }
261
262    /// Falls back to the executed blocks tracked in memory, because the store only buffers side
263    /// chain BALs briefly and never persists them.
264    fn get_bals_by_hashes_with_limit(
265        &self,
266        block_hashes: &[BlockHash],
267        limit: GetBlockAccessListLimit,
268    ) -> ProviderResult<Vec<Option<Bytes>>> {
269        let mut bals = self.bal_store.get_by_hashes_with_limit(block_hashes, limit)?;
270        for (bal, hash) in bals.iter_mut().zip(block_hashes).filter(|(bal, _)| bal.is_none()) {
271            *bal = self.database.in_memory_state().state_by_hash(*hash).and_then(|state| {
272                state.block_ref().bal().map(|bal| bal.as_raw_bal().as_raw().clone())
273            });
274        }
275        // Filled BALs only grow the response, so the limit can only cut it shorter.
276        let mut size = 0;
277        if let Some(last) = bals.iter().position(|bal| {
278            size += bal.as_ref().map_or(1, |bytes| bytes.len());
279            limit.exceeds(size)
280        }) {
281            bals.truncate(last + 1);
282        }
283        Ok(bals)
284    }
285}
286
287/// State range view backed by one resolved historical overlay.
288struct HistoricalStateRangeView<N: ProviderNodeTypes> {
289    provider: HistoricalStateRangeProvider<N>,
290}
291
292impl<N: ProviderNodeTypes> StateRangeProviderFactory for BlockchainProvider<N> {
293    /// Resolves a retained canonical state root into a pinned range view, preferring a still
294    /// in-memory block over the persisted-history fallback. Resolves nothing while a snap attempt
295    /// is unverified, since no root describes its partially downloaded state, or while the
296    /// `Execution` checkpoint is ahead of `Finish`.
297    fn state_range_provider(&self, state_root: B256) -> ProviderResult<Option<StateRangeView>> {
298        // Persisted blocks leave memory only after their commit, so a canonical root missed here is
299        // already visible to a snapshot opened afterwards.
300        let block_state = self.block_state_by_root(state_root);
301        self.state_range_view(self.database.provider()?, block_state, state_root)
302    }
303}
304
305impl<N: ProviderNodeTypes> StateRangeProvider for HistoricalStateRangeView<N> {
306    fn account_range(
307        &self,
308        start: B256,
309        limit: B256,
310        response_bytes: usize,
311    ) -> RangeResult<(B256, Account)> {
312        let mut cursor = self.provider.hashed_account_cursor().map_err(ProviderError::Database)?;
313
314        let mut accounts = Vec::new();
315        let mut total_bytes = 0usize;
316        let mut end = RangeEnd::Exhausted;
317
318        // Append before checking `limit`, so an empty `[start, limit]` still returns the account
319        // right past `limit`, provable as an empty range rather than a skipped one.
320        let mut entry = cursor.seek(start).map_err(ProviderError::Database)?;
321        while let Some((hash, account)) = entry {
322            total_bytes += 32 + 4 * 32; // hash + rough upper bound of the RLP account body
323            accounts.push((hash, account));
324            if hash >= limit {
325                end = RangeEnd::HashLimit;
326                break
327            }
328            if total_bytes > response_bytes {
329                end = RangeEnd::ByteLimit;
330                break
331            }
332            entry = cursor.next().map_err(ProviderError::Database)?;
333        }
334
335        Ok(RangeResponse { items: accounts, end })
336    }
337
338    fn storage_root_by_hash(&self, hashed_address: B256) -> ProviderResult<B256> {
339        let root = StorageRoot::new_hashed(
340            &self.provider,
341            &self.provider,
342            hashed_address,
343            Default::default(),
344            TrieRootMetrics::new(TrieType::Storage),
345        )
346        .root()
347        .map_err(|err| ProviderError::Database(err.into()))?;
348        Ok(root)
349    }
350
351    fn storage_range(
352        &self,
353        hashed_address: B256,
354        start: B256,
355        limit: B256,
356        response_bytes: usize,
357    ) -> StorageRangeResult {
358        // Distinguish an absent account from one with no storage, so callers don't silently
359        // omit it and shift later accounts' positions.
360        let mut account_cursor =
361            self.provider.hashed_account_cursor().map_err(ProviderError::Database)?;
362        let found = account_cursor.seek(hashed_address).map_err(ProviderError::Database)?;
363        if found.map(|(hash, _)| hash) != Some(hashed_address) {
364            return Ok(None)
365        }
366
367        let mut cursor =
368            self.provider.hashed_storage_cursor(hashed_address).map_err(ProviderError::Database)?;
369
370        let mut slots = Vec::new();
371        let mut total_bytes = 0usize;
372        let mut end = RangeEnd::Exhausted;
373
374        // Append before checking `limit`, so an empty `[start, limit]` still returns the slot
375        // right past `limit`, provable as an empty range rather than a skipped one.
376        let mut entry = cursor.seek(start).map_err(ProviderError::Database)?;
377        while let Some((hash, value)) = entry {
378            total_bytes += 64;
379            slots.push((hash, value));
380            if hash >= limit {
381                end = RangeEnd::HashLimit;
382                break
383            }
384            if total_bytes > response_bytes {
385                end = RangeEnd::ByteLimit;
386                break
387            }
388            entry = cursor.next().map_err(ProviderError::Database)?;
389        }
390
391        Ok(Some(RangeResponse { items: slots, end }))
392    }
393
394    fn account_range_proof(&self, keys: &[B256]) -> ProviderResult<Vec<Bytes>> {
395        let multiproof = Proof::new(&self.provider, &self.provider)
396            .multiproof(MultiProofTargets::accounts(keys.iter().copied()))?;
397        Ok(multiproof
398            .account_subtree
399            .into_nodes_sorted()
400            .into_iter()
401            .map(|(_, bytes)| bytes)
402            .collect())
403    }
404
405    fn storage_range_proof(
406        &self,
407        hashed_address: B256,
408        keys: &[B256],
409    ) -> ProviderResult<Vec<Bytes>> {
410        let multiproof = StorageProof::new_hashed(&self.provider, &self.provider, hashed_address)
411            .storage_multiproof(keys.iter().copied().collect())?;
412        Ok(multiproof.subtree.into_nodes_sorted().into_iter().map(|(_, bytes)| bytes).collect())
413    }
414}
415
416/// Returns the hash of the canonical block with `state_root` among those retained up to `finish`,
417/// as seen by `provider`.
418fn retained_block_hash<N: ProviderNodeTypes>(
419    provider: &StateRangeDbProvider<N>,
420    finish: BlockNumber,
421    state_root: B256,
422) -> ProviderResult<Option<B256>> {
423    let oldest = finish.saturating_sub(SNAPSHOT_STATE_RETENTION - 1);
424
425    for number in (oldest..=finish).rev() {
426        let Some(header) = provider.sealed_header(number)? else { continue };
427        if header.state_root() == state_root {
428            return Ok(Some(header.hash()))
429        }
430    }
431    Ok(None)
432}
433
434impl<N: ProviderNodeTypes> DatabaseProviderFactory for BlockchainProvider<N> {
435    type DB = N::DB;
436    type Provider = <ProviderFactory<N> as DatabaseProviderFactory>::Provider;
437    type ProviderRW = <ProviderFactory<N> as DatabaseProviderFactory>::ProviderRW;
438
439    fn database_provider_ro(&self) -> ProviderResult<Self::Provider> {
440        DatabaseProviderFactory::database_provider_ro(&self.database)
441    }
442
443    fn database_provider_rw(&self) -> ProviderResult<Self::ProviderRW> {
444        DatabaseProviderFactory::database_provider_rw(&self.database)
445    }
446}
447
448impl<N: ProviderNodeTypes> AsRef<N::DB> for BlockchainProvider<N> {
449    fn as_ref(&self) -> &N::DB {
450        self.database.db_ref()
451    }
452}
453
454impl<N: ProviderNodeTypes> StaticFileProviderFactory for BlockchainProvider<N> {
455    fn static_file_provider(&self) -> StaticFileProvider<Self::Primitives> {
456        self.database.static_file_provider()
457    }
458
459    fn get_static_file_writer(
460        &self,
461        block: BlockNumber,
462        segment: StaticFileSegment,
463    ) -> ProviderResult<StaticFileProviderRWRefMut<'_, Self::Primitives>> {
464        self.database.get_static_file_writer(block, segment)
465    }
466}
467
468impl<N: ProviderNodeTypes> RocksDBProviderFactory for BlockchainProvider<N> {
469    fn rocksdb_provider(&self) -> RocksDBProvider {
470        self.database.rocksdb_provider()
471    }
472
473    fn set_pending_rocksdb_batch(&self, _batch: rocksdb::WriteBatchWithTransaction<true>) {
474        unimplemented!("BlockchainProvider wraps ProviderFactory - use DatabaseProvider::set_pending_rocksdb_batch instead")
475    }
476
477    fn commit_pending_rocksdb_batches(&self) -> ProviderResult<()> {
478        unimplemented!("BlockchainProvider wraps ProviderFactory - use DatabaseProvider::commit_pending_rocksdb_batches instead")
479    }
480}
481
482impl<N: ProviderNodeTypes> HeaderProvider for BlockchainProvider<N> {
483    type Header = HeaderTy<N>;
484
485    fn header(&self, block_hash: BlockHash) -> ProviderResult<Option<Self::Header>> {
486        self.consistent_provider()?.header(block_hash)
487    }
488
489    fn header_by_number(&self, num: BlockNumber) -> ProviderResult<Option<Self::Header>> {
490        self.consistent_provider()?.header_by_number(num)
491    }
492
493    fn headers_range(
494        &self,
495        range: impl RangeBounds<BlockNumber>,
496    ) -> ProviderResult<Vec<Self::Header>> {
497        self.consistent_provider()?.headers_range(range)
498    }
499
500    fn sealed_header(
501        &self,
502        number: BlockNumber,
503    ) -> ProviderResult<Option<SealedHeader<Self::Header>>> {
504        self.consistent_provider()?.sealed_header(number)
505    }
506
507    fn sealed_headers_range(
508        &self,
509        range: impl RangeBounds<BlockNumber>,
510    ) -> ProviderResult<Vec<SealedHeader<Self::Header>>> {
511        self.consistent_provider()?.sealed_headers_range(range)
512    }
513
514    fn sealed_headers_while(
515        &self,
516        range: impl RangeBounds<BlockNumber>,
517        predicate: impl FnMut(&SealedHeader<Self::Header>) -> bool,
518    ) -> ProviderResult<Vec<SealedHeader<Self::Header>>> {
519        self.consistent_provider()?.sealed_headers_while(range, predicate)
520    }
521}
522
523impl<N: ProviderNodeTypes> BlockHashReader for BlockchainProvider<N> {
524    fn block_hash(&self, number: u64) -> ProviderResult<Option<B256>> {
525        self.consistent_provider()?.block_hash(number)
526    }
527
528    fn canonical_hashes_range(
529        &self,
530        start: BlockNumber,
531        end: BlockNumber,
532    ) -> ProviderResult<Vec<B256>> {
533        self.consistent_provider()?.canonical_hashes_range(start, end)
534    }
535}
536
537impl<N: ProviderNodeTypes> BlockNumReader for BlockchainProvider<N> {
538    fn chain_info(&self) -> ProviderResult<ChainInfo> {
539        Ok(self.canonical_in_memory_state.chain_info())
540    }
541
542    fn best_block_number(&self) -> ProviderResult<BlockNumber> {
543        Ok(self.canonical_in_memory_state.get_canonical_block_number())
544    }
545
546    fn last_block_number(&self) -> ProviderResult<BlockNumber> {
547        self.database.last_block_number()
548    }
549
550    fn earliest_block_number(&self) -> ProviderResult<BlockNumber> {
551        self.database.earliest_block_number()
552    }
553
554    fn block_number(&self, hash: B256) -> ProviderResult<Option<BlockNumber>> {
555        self.consistent_provider()?.block_number(hash)
556    }
557}
558
559impl<N: ProviderNodeTypes> BlockIdReader for BlockchainProvider<N> {
560    fn pending_block_num_hash(&self) -> ProviderResult<Option<BlockNumHash>> {
561        Ok(self.canonical_in_memory_state.pending_block_num_hash())
562    }
563
564    fn safe_block_num_hash(&self) -> ProviderResult<Option<BlockNumHash>> {
565        Ok(self.canonical_in_memory_state.get_safe_num_hash())
566    }
567
568    fn finalized_block_num_hash(&self) -> ProviderResult<Option<BlockNumHash>> {
569        Ok(self.canonical_in_memory_state.get_finalized_num_hash())
570    }
571}
572
573impl<N: ProviderNodeTypes> BlockReader for BlockchainProvider<N> {
574    type Block = BlockTy<N>;
575
576    fn find_block_by_hash(
577        &self,
578        hash: B256,
579        source: BlockSource,
580    ) -> ProviderResult<Option<Self::Block>> {
581        self.consistent_provider()?.find_block_by_hash(hash, source)
582    }
583
584    fn find_sealed_or_recovered_block(
585        &self,
586        hash: B256,
587        source: BlockSource,
588    ) -> ProviderResult<Option<SealedOrRecoveredBlock<Self::Block>>> {
589        self.consistent_provider()?.find_sealed_or_recovered_block(hash, source)
590    }
591
592    fn block(&self, id: BlockHashOrNumber) -> ProviderResult<Option<Self::Block>> {
593        self.consistent_provider()?.block(id)
594    }
595
596    fn pending_block(&self) -> ProviderResult<Option<Arc<RecoveredBlock<Self::Block>>>> {
597        Ok(self.canonical_in_memory_state.pending_recovered_block())
598    }
599
600    fn pending_block_and_receipts(
601        &self,
602    ) -> ProviderResult<Option<RecoveredBlockAndExecutionOutput<Self::Block, Self::Receipt>>> {
603        Ok(self.canonical_in_memory_state.pending_block_and_receipts())
604    }
605
606    /// Returns the block with senders with matching number or hash from database.
607    ///
608    /// **NOTE: If [`TransactionVariant::NoHash`] is provided then the transactions have invalid
609    /// hashes, since they would need to be calculated on the spot, and we want fast querying.**
610    ///
611    /// Returns `None` if block is not found.
612    fn recovered_block(
613        &self,
614        id: BlockHashOrNumber,
615        transaction_kind: TransactionVariant,
616    ) -> ProviderResult<Option<RecoveredBlock<Self::Block>>> {
617        self.consistent_provider()?.recovered_block(id, transaction_kind)
618    }
619
620    fn sealed_block_with_senders(
621        &self,
622        id: BlockHashOrNumber,
623        transaction_kind: TransactionVariant,
624    ) -> ProviderResult<Option<RecoveredBlock<Self::Block>>> {
625        self.consistent_provider()?.sealed_block_with_senders(id, transaction_kind)
626    }
627
628    fn block_range(&self, range: RangeInclusive<BlockNumber>) -> ProviderResult<Vec<Self::Block>> {
629        self.consistent_provider()?.block_range(range)
630    }
631
632    fn block_with_senders_range(
633        &self,
634        range: RangeInclusive<BlockNumber>,
635    ) -> ProviderResult<Vec<RecoveredBlock<Self::Block>>> {
636        self.consistent_provider()?.block_with_senders_range(range)
637    }
638
639    fn recovered_block_range(
640        &self,
641        range: RangeInclusive<BlockNumber>,
642    ) -> ProviderResult<Vec<RecoveredBlock<Self::Block>>> {
643        self.consistent_provider()?.recovered_block_range(range)
644    }
645
646    fn block_by_transaction_id(&self, id: TxNumber) -> ProviderResult<Option<BlockNumber>> {
647        self.consistent_provider()?.block_by_transaction_id(id)
648    }
649}
650
651impl<N: ProviderNodeTypes> TransactionsProvider for BlockchainProvider<N> {
652    type Transaction = TxTy<N>;
653
654    fn transaction_id(&self, tx_hash: TxHash) -> ProviderResult<Option<TxNumber>> {
655        self.consistent_provider()?.transaction_id(tx_hash)
656    }
657
658    fn transaction_by_id(&self, id: TxNumber) -> ProviderResult<Option<Self::Transaction>> {
659        self.consistent_provider()?.transaction_by_id(id)
660    }
661
662    fn transaction_by_id_unhashed(
663        &self,
664        id: TxNumber,
665    ) -> ProviderResult<Option<Self::Transaction>> {
666        self.consistent_provider()?.transaction_by_id_unhashed(id)
667    }
668
669    fn transaction_by_hash(&self, hash: TxHash) -> ProviderResult<Option<Self::Transaction>> {
670        self.consistent_provider()?.transaction_by_hash(hash)
671    }
672
673    fn transaction_by_hash_with_meta(
674        &self,
675        tx_hash: TxHash,
676    ) -> ProviderResult<Option<(Self::Transaction, TransactionMeta)>> {
677        self.consistent_provider()?.transaction_by_hash_with_meta(tx_hash)
678    }
679
680    fn transaction_by_hash_with_meta_and_sender(
681        &self,
682        tx_hash: TxHash,
683    ) -> ProviderResult<Option<(Self::Transaction, TransactionMeta, Option<Address>)>> {
684        self.consistent_provider()?.transaction_by_hash_with_meta_and_sender(tx_hash)
685    }
686
687    fn transactions_by_block(
688        &self,
689        id: BlockHashOrNumber,
690    ) -> ProviderResult<Option<Vec<Self::Transaction>>> {
691        self.consistent_provider()?.transactions_by_block(id)
692    }
693
694    fn transactions_by_block_range(
695        &self,
696        range: impl RangeBounds<BlockNumber>,
697    ) -> ProviderResult<Vec<Vec<Self::Transaction>>> {
698        self.consistent_provider()?.transactions_by_block_range(range)
699    }
700
701    fn transactions_by_tx_range(
702        &self,
703        range: impl RangeBounds<TxNumber>,
704    ) -> ProviderResult<Vec<Self::Transaction>> {
705        self.consistent_provider()?.transactions_by_tx_range(range)
706    }
707
708    fn senders_by_tx_range(
709        &self,
710        range: impl RangeBounds<TxNumber>,
711    ) -> ProviderResult<Vec<Address>> {
712        self.consistent_provider()?.senders_by_tx_range(range)
713    }
714
715    fn transaction_sender(&self, id: TxNumber) -> ProviderResult<Option<Address>> {
716        self.consistent_provider()?.transaction_sender(id)
717    }
718}
719
720impl<N: ProviderNodeTypes> ReceiptProvider for BlockchainProvider<N> {
721    type Receipt = ReceiptTy<N>;
722
723    fn receipt(&self, id: TxNumber) -> ProviderResult<Option<Self::Receipt>> {
724        self.consistent_provider()?.receipt(id)
725    }
726
727    fn receipt_by_hash(&self, hash: TxHash) -> ProviderResult<Option<Self::Receipt>> {
728        self.consistent_provider()?.receipt_by_hash(hash)
729    }
730
731    fn receipts_by_block(
732        &self,
733        block: BlockHashOrNumber,
734    ) -> ProviderResult<Option<Vec<Self::Receipt>>> {
735        self.consistent_provider()?.receipts_by_block(block)
736    }
737
738    fn receipts_by_tx_range(
739        &self,
740        range: impl RangeBounds<TxNumber>,
741    ) -> ProviderResult<Vec<Self::Receipt>> {
742        self.consistent_provider()?.receipts_by_tx_range(range)
743    }
744
745    fn receipts_by_block_range(
746        &self,
747        block_range: RangeInclusive<BlockNumber>,
748    ) -> ProviderResult<Vec<Vec<Self::Receipt>>> {
749        self.consistent_provider()?.receipts_by_block_range(block_range)
750    }
751}
752
753impl<N: ProviderNodeTypes> ReceiptProviderIdExt for BlockchainProvider<N> {
754    fn receipts_by_block_id(&self, block: BlockId) -> ProviderResult<Option<Vec<Self::Receipt>>> {
755        self.consistent_provider()?.receipts_by_block_id(block)
756    }
757}
758
759impl<N: ProviderNodeTypes> BlockBodyIndicesProvider for BlockchainProvider<N> {
760    fn block_body_indices(
761        &self,
762        number: BlockNumber,
763    ) -> ProviderResult<Option<StoredBlockBodyIndices>> {
764        self.consistent_provider()?.block_body_indices(number)
765    }
766
767    fn block_body_indices_range(
768        &self,
769        range: RangeInclusive<BlockNumber>,
770    ) -> ProviderResult<Vec<StoredBlockBodyIndices>> {
771        self.consistent_provider()?.block_body_indices_range(range)
772    }
773}
774
775impl<N: ProviderNodeTypes> reth_storage_api::DurableBlockReader for BlockchainProvider<N> {
776    fn last_durable_block_num_hash(&self) -> ProviderResult<alloy_eips::BlockNumHash> {
777        // Read the database, not in-memory blocks that may be on an unpersisted fork.
778        self.database.last_durable_block_num_hash()
779    }
780}
781
782impl<N: ProviderNodeTypes> StageCheckpointReader for BlockchainProvider<N> {
783    fn get_stage_checkpoint(&self, id: StageId) -> ProviderResult<Option<StageCheckpoint>> {
784        self.consistent_provider()?.get_stage_checkpoint(id)
785    }
786
787    fn get_stage_checkpoint_progress(&self, id: StageId) -> ProviderResult<Option<Vec<u8>>> {
788        self.consistent_provider()?.get_stage_checkpoint_progress(id)
789    }
790
791    fn get_all_checkpoints(&self) -> ProviderResult<Vec<(String, StageCheckpoint)>> {
792        self.consistent_provider()?.get_all_checkpoints()
793    }
794}
795
796impl<N: ProviderNodeTypes> PruneCheckpointReader for BlockchainProvider<N> {
797    fn get_prune_checkpoint(
798        &self,
799        segment: PruneSegment,
800    ) -> ProviderResult<Option<PruneCheckpoint>> {
801        self.consistent_provider()?.get_prune_checkpoint(segment)
802    }
803
804    fn get_prune_checkpoints(&self) -> ProviderResult<Vec<(PruneSegment, PruneCheckpoint)>> {
805        self.consistent_provider()?.get_prune_checkpoints()
806    }
807
808    fn get_prune_checkpoints_for_availability(
809        &self,
810    ) -> ProviderResult<Vec<(PruneSegment, PruneCheckpoint)>> {
811        self.consistent_provider()?.get_prune_checkpoints_for_availability()
812    }
813}
814
815impl<N: NodeTypesWithDB> ChainSpecProvider for BlockchainProvider<N> {
816    type ChainSpec = N::ChainSpec;
817
818    fn chain_spec(&self) -> Arc<N::ChainSpec> {
819        self.database.chain_spec()
820    }
821}
822
823impl<N: ProviderNodeTypes> StateProviderFactory for BlockchainProvider<N> {
824    type Primitives = N::Primitives;
825
826    /// Storage provider for latest block
827    fn latest(&self) -> ProviderResult<StateProviderBox> {
828        trace!(target: "providers::blockchain", "Getting latest block state provider");
829        // use latest state provider if the head state exists
830        if let Some(state) = self.canonical_in_memory_state.head_state() {
831            trace!(target: "providers::blockchain", "Using head state for latest state provider");
832            self.state_provider_for_state(state)
833        } else {
834            trace!(target: "providers::blockchain", "Using database state for latest state provider");
835            self.database.latest()
836        }
837    }
838
839    fn state_with_block_appended(
840        &self,
841        parent_hash: BlockHash,
842        block: ExecutedBlock<N::Primitives>,
843    ) -> ProviderResult<StateProviderBox> {
844        let state_provider_factory = OverlayStateProviderFactory::new(
845            self.database.clone(),
846            self.database.overlay_manager().overlay_builder(parent_hash).with_appended_block(block),
847        );
848        Ok(Box::new(state_provider_factory.database_provider_ro()?))
849    }
850
851    /// Returns a [`StateProviderBox`] indexed by the given block number or tag.
852    fn state_by_block_number_or_tag(
853        &self,
854        number_or_tag: BlockNumberOrTag,
855    ) -> ProviderResult<StateProviderBox> {
856        match number_or_tag {
857            BlockNumberOrTag::Latest => self.latest(),
858            BlockNumberOrTag::Finalized => {
859                // we can only get the finalized state by hash, not by num
860                let hash =
861                    self.finalized_block_hash()?.ok_or(ProviderError::FinalizedBlockNotFound)?;
862                self.state_by_block_hash(hash)
863            }
864            BlockNumberOrTag::Safe => {
865                // we can only get the safe state by hash, not by num
866                let hash = self.safe_block_hash()?.ok_or(ProviderError::SafeBlockNotFound)?;
867                self.state_by_block_hash(hash)
868            }
869            BlockNumberOrTag::Earliest => {
870                self.history_by_block_number(self.earliest_block_number()?)
871            }
872            BlockNumberOrTag::Pending => self.pending(),
873            BlockNumberOrTag::Number(num) => {
874                let hash = self
875                    .block_hash(num)?
876                    .ok_or_else(|| ProviderError::HeaderNotFound(num.into()))?;
877                self.state_by_block_hash(hash)
878            }
879        }
880    }
881
882    fn history_by_block_number(
883        &self,
884        block_number: BlockNumber,
885    ) -> ProviderResult<StateProviderBox> {
886        trace!(target: "providers::blockchain", ?block_number, "Getting history by block number");
887        let provider = self.consistent_provider()?;
888        let hash = provider
889            .block_hash(block_number)?
890            .ok_or_else(|| ProviderError::HeaderNotFound(block_number.into()))?;
891        Ok(self.state_provider_from_database(provider.into_database_provider(), hash))
892    }
893
894    fn history_by_block_hash(&self, block_hash: BlockHash) -> ProviderResult<StateProviderBox> {
895        trace!(target: "providers::blockchain", ?block_hash, "Getting history by block hash");
896        let provider = self.consistent_provider()?;
897        provider.block_number(block_hash)?.ok_or(ProviderError::BlockHashNotFound(block_hash))?;
898        Ok(self.state_provider_from_database(provider.into_database_provider(), block_hash))
899    }
900
901    fn state_by_block_hash(&self, hash: BlockHash) -> ProviderResult<StateProviderBox> {
902        trace!(target: "providers::blockchain", ?hash, "Getting state by block hash");
903        if let Some(state) = self.canonical_in_memory_state.state_by_hash(hash) {
904            self.state_provider_for_state(state)
905        } else if let Ok(state) = self.history_by_block_hash(hash) {
906            // This could be tracked by a historical block
907            Ok(state)
908        } else if let Ok(Some(pending)) = self.pending_state_by_hash(hash) {
909            // .. or this could be the pending state
910            Ok(pending)
911        } else {
912            // if we couldn't find it anywhere, then we should return an error
913            Err(ProviderError::StateForHashNotFound(hash))
914        }
915    }
916
917    /// Returns the state provider for pending state.
918    ///
919    /// If there's no pending block available then the latest state provider is returned:
920    /// [`Self::latest`]
921    fn pending(&self) -> ProviderResult<StateProviderBox> {
922        trace!(target: "providers::blockchain", "Getting provider for pending state");
923
924        if let Some(pending) = self.canonical_in_memory_state.pending_state() {
925            // we have a pending block
926            return self.state_provider_for_state(pending);
927        }
928
929        // fallback to latest state if the pending block is not available
930        self.latest()
931    }
932
933    fn pending_state_by_hash(&self, block_hash: B256) -> ProviderResult<Option<StateProviderBox>> {
934        if let Some(pending) = self.canonical_in_memory_state.pending_state() &&
935            pending.hash() == block_hash
936        {
937            return self.state_provider_for_state(pending).map(Some);
938        }
939        Ok(None)
940    }
941
942    fn maybe_pending(&self) -> ProviderResult<Option<StateProviderBox>> {
943        if let Some(pending) = self.canonical_in_memory_state.pending_state() {
944            return self.state_provider_for_state(pending).map(Some)
945        }
946
947        Ok(None)
948    }
949}
950
951impl<N: ProviderNodeTypes> CanonChainTracker for BlockchainProvider<N> {
952    type Header = HeaderTy<N>;
953
954    fn on_forkchoice_update_received(&self, _update: &ForkchoiceState) {
955        // update timestamp
956        self.canonical_in_memory_state.on_forkchoice_update_received();
957    }
958
959    fn last_received_update_timestamp(&self) -> Option<Instant> {
960        self.canonical_in_memory_state.last_received_update_timestamp()
961    }
962
963    fn set_canonical_head(&self, header: SealedHeader<Self::Header>) {
964        self.canonical_in_memory_state.set_canonical_head(header);
965    }
966
967    fn set_safe(&self, header: SealedHeader<Self::Header>) {
968        self.canonical_in_memory_state.set_safe(header);
969    }
970
971    fn set_finalized(&self, header: SealedHeader<Self::Header>) {
972        self.canonical_in_memory_state.set_finalized(header);
973    }
974}
975
976impl<N: ProviderNodeTypes> BlockReaderIdExt for BlockchainProvider<N>
977where
978    Self: ReceiptProviderIdExt,
979{
980    fn block_by_id(&self, id: BlockId) -> ProviderResult<Option<Self::Block>> {
981        self.consistent_provider()?.block_by_id(id)
982    }
983
984    fn header_by_number_or_tag(
985        &self,
986        id: BlockNumberOrTag,
987    ) -> ProviderResult<Option<Self::Header>> {
988        match id {
989            BlockNumberOrTag::Latest |
990            BlockNumberOrTag::Finalized |
991            BlockNumberOrTag::Safe |
992            BlockNumberOrTag::Pending => {
993                Ok(self.sealed_header_by_number_or_tag(id)?.map(|h| h.unseal()))
994            }
995            BlockNumberOrTag::Earliest | BlockNumberOrTag::Number(_) => {
996                self.consistent_provider()?.header_by_number_or_tag(id)
997            }
998        }
999    }
1000
1001    fn sealed_header_by_number_or_tag(
1002        &self,
1003        id: BlockNumberOrTag,
1004    ) -> ProviderResult<Option<SealedHeader<Self::Header>>> {
1005        match id {
1006            BlockNumberOrTag::Latest => {
1007                Ok(Some(self.canonical_in_memory_state.get_canonical_head()))
1008            }
1009            BlockNumberOrTag::Finalized => {
1010                Ok(self.canonical_in_memory_state.get_finalized_header())
1011            }
1012            BlockNumberOrTag::Safe => Ok(self.canonical_in_memory_state.get_safe_header()),
1013            BlockNumberOrTag::Pending => Ok(self.canonical_in_memory_state.pending_sealed_header()),
1014            BlockNumberOrTag::Earliest | BlockNumberOrTag::Number(_) => {
1015                self.consistent_provider()?.sealed_header_by_number_or_tag(id)
1016            }
1017        }
1018    }
1019
1020    fn sealed_header_by_id(
1021        &self,
1022        id: BlockId,
1023    ) -> ProviderResult<Option<SealedHeader<Self::Header>>> {
1024        match id {
1025            BlockId::Number(tag) => self.sealed_header_by_number_or_tag(tag),
1026            BlockId::Hash(_) => self.consistent_provider()?.sealed_header_by_id(id),
1027        }
1028    }
1029
1030    fn header_by_id(&self, id: BlockId) -> ProviderResult<Option<Self::Header>> {
1031        match id {
1032            BlockId::Number(tag) => self.header_by_number_or_tag(tag),
1033            BlockId::Hash(_) => self.consistent_provider()?.header_by_id(id),
1034        }
1035    }
1036}
1037
1038impl<N: ProviderNodeTypes> CanonStateSubscriptions for BlockchainProvider<N> {
1039    type Primitives = N::Primitives;
1040
1041    fn subscribe_to_canonical_state(&self) -> CanonStateNotifications<Self::Primitives> {
1042        self.canonical_in_memory_state.subscribe_canon_state()
1043    }
1044}
1045
1046impl<N: ProviderNodeTypes> ForkChoiceSubscriptions for BlockchainProvider<N> {
1047    type Header = HeaderTy<N>;
1048
1049    fn subscribe_safe_block(&self) -> ForkChoiceNotifications<Self::Header> {
1050        let receiver = self.canonical_in_memory_state.subscribe_safe_block();
1051        ForkChoiceNotifications(receiver)
1052    }
1053
1054    fn subscribe_finalized_block(&self) -> ForkChoiceNotifications<Self::Header> {
1055        let receiver = self.canonical_in_memory_state.subscribe_finalized_block();
1056        ForkChoiceNotifications(receiver)
1057    }
1058}
1059
1060impl<N: ProviderNodeTypes> PersistedBlockSubscriptions for BlockchainProvider<N> {
1061    fn subscribe_persisted_block(&self) -> PersistedBlockNotifications {
1062        let receiver = self.canonical_in_memory_state.subscribe_persisted_block();
1063        PersistedBlockNotifications(receiver)
1064    }
1065}
1066
1067impl<N: ProviderNodeTypes> StorageChangeSetReader for BlockchainProvider<N> {
1068    fn storage_changeset(
1069        &self,
1070        block_number: BlockNumber,
1071    ) -> ProviderResult<Vec<(BlockNumberAddress, StorageEntry)>> {
1072        self.consistent_provider()?.storage_changeset(block_number)
1073    }
1074
1075    fn get_storage_before_block(
1076        &self,
1077        block_number: BlockNumber,
1078        address: Address,
1079        storage_key: B256,
1080    ) -> ProviderResult<Option<StorageEntry>> {
1081        self.consistent_provider()?.get_storage_before_block(block_number, address, storage_key)
1082    }
1083
1084    fn storage_changesets_range(
1085        &self,
1086        range: impl RangeBounds<BlockNumber>,
1087    ) -> ProviderResult<Vec<(BlockNumberAddress, StorageEntry)>> {
1088        self.consistent_provider()?.storage_changesets_range(range)
1089    }
1090}
1091
1092impl<N: ProviderNodeTypes> ChangeSetReader for BlockchainProvider<N> {
1093    fn account_block_changeset(
1094        &self,
1095        block_number: BlockNumber,
1096    ) -> ProviderResult<Vec<AccountBeforeTx>> {
1097        self.consistent_provider()?.account_block_changeset(block_number)
1098    }
1099
1100    fn get_account_before_block(
1101        &self,
1102        block_number: BlockNumber,
1103        address: Address,
1104    ) -> ProviderResult<Option<AccountBeforeTx>> {
1105        self.consistent_provider()?.get_account_before_block(block_number, address)
1106    }
1107
1108    fn account_changesets_range(
1109        &self,
1110        range: impl core::ops::RangeBounds<BlockNumber>,
1111    ) -> ProviderResult<Vec<(BlockNumber, AccountBeforeTx)>> {
1112        self.consistent_provider()?.account_changesets_range(range)
1113    }
1114}
1115
1116impl<N: ProviderNodeTypes> StateReader for BlockchainProvider<N> {
1117    type Receipt = ReceiptTy<N>;
1118
1119    /// Re-constructs the [`ExecutionOutcome`] from in-memory and database state, if necessary.
1120    ///
1121    /// If data for the block does not exist, this will return [`None`].
1122    ///
1123    /// NOTE: This cannot be called safely in a loop outside of the blockchain tree thread. This is
1124    /// because the [`CanonicalInMemoryState`] could change during a reorg, causing results to be
1125    /// inconsistent. Currently this can safely be called within the blockchain tree thread,
1126    /// because the tree thread is responsible for modifying the [`CanonicalInMemoryState`] in the
1127    /// first place.
1128    fn get_state(
1129        &self,
1130        block: BlockNumber,
1131    ) -> ProviderResult<Option<ExecutionOutcome<Self::Receipt>>> {
1132        if let Some(head) = self.canonical_in_memory_state.head_state() &&
1133            let Some(state) = head.block_on_chain(block.into())
1134        {
1135            return Ok(Some(ExecutionOutcome::from((
1136                state.block_ref().execution_outcome().clone(),
1137                block,
1138            ))))
1139        }
1140
1141        let provider = self.database.provider()?;
1142        let Some(block_body) = provider.block_body_indices(block)? else { return Ok(None) };
1143
1144        let account_changeset = provider.account_changesets_range(block..=block)?;
1145        let storage_changeset = provider.storage_changeset(block)?;
1146
1147        let Some(block_hash) = provider.block_hash(block)? else { return Ok(None) };
1148        let state_provider = OverlayStateProvider::<&_, N::Primitives>::new_ref(
1149            &provider,
1150            self.database.overlay_manager().overlay_builder(block_hash),
1151        );
1152        let (state, reverts) = provider.populate_bundle_state(
1153            account_changeset,
1154            storage_changeset,
1155            |address| state_provider.basic_account(&address),
1156            |address, storage_key| state_provider.storage(address, storage_key),
1157        )?;
1158        let receipts = provider.receipts_by_tx_range(block_body.tx_num_range())?;
1159
1160        Ok(Some(ExecutionOutcome::new_init(
1161            state,
1162            reverts,
1163            // We skip new contracts since we never delete them from the database
1164            Vec::new(),
1165            vec![receipts],
1166            block,
1167            Vec::new(),
1168        )))
1169    }
1170}
1171
1172#[cfg(test)]
1173#[allow(clippy::clone_on_copy)]
1174mod tests {
1175    use super::*;
1176    use crate::{
1177        providers::BlockchainProvider,
1178        test_utils::{
1179            create_test_provider_factory, create_test_provider_factory_with_chain_spec,
1180            MockNodeTypesWithDB,
1181        },
1182        BlockWriter, CanonChainTracker, ProviderFactory, SaveBlocksInput,
1183    };
1184    use alloy_consensus::constants::EMPTY_ROOT_HASH;
1185    use alloy_eips::{BlockHashOrNumber, BlockId, BlockNumHash, BlockNumberOrTag};
1186    use alloy_primitives::{keccak256, Address, BlockNumber, Bytes, TxNumber, B256, U256};
1187    use evm2::evm::AccountInfo;
1188    use itertools::Itertools;
1189    use rand::Rng;
1190    use reth_chain_state::{
1191        test_utils::TestBlockBuilder, CanonStateNotification, CanonStateSubscriptions,
1192        CanonicalInMemoryState, ExecutedBlock, NewCanonicalChain,
1193    };
1194    use reth_chainspec::{ChainSpec, MAINNET};
1195    use reth_db_api::models::{AccountBeforeTx, SnapAttempt, StoredBlockBodyIndices};
1196    use reth_errors::ProviderError;
1197    use reth_ethereum_primitives::{Block, Receipt};
1198    use reth_execution_types::{
1199        BlockExecutionOutput, BlockExecutionResult, Chain, DecodedEvmBal, ExecutionOutcome,
1200    };
1201    use reth_primitives_traits::{
1202        Account, Block as _, RecoveredBlock, SealedBlock, SignerRecoverable, StorageEntry,
1203    };
1204    use reth_stages_types::{StageCheckpoint, StageId};
1205    use reth_storage_api::{
1206        BalProvider, BlockBodyIndicesProvider, BlockHashReader, BlockIdReader, BlockNumReader,
1207        BlockReader, BlockReaderIdExt, BlockSource, ChangeSetReader, DBProvider,
1208        DatabaseProviderFactory, HashingWriter, HeaderProvider, MetadataWriter, RangeEnd,
1209        ReceiptProvider, ReceiptProviderIdExt, StageCheckpointWriter, StateProviderFactory,
1210        StateRangeProvider, StateRangeProviderFactory, StateRootProvider, StateWriteConfig,
1211        StateWriter, StorageRootProvider, StorageSettings, StorageSettingsCache,
1212        TransactionVariant, TransactionsProvider, TrieWriter,
1213    };
1214    use reth_testing_utils::generators::{
1215        self, random_block, random_block_range, random_changeset_range, random_eoa_accounts,
1216        random_receipt, BlockParams, BlockRangeParams,
1217    };
1218    use reth_trie::{
1219        bundle_state::{BundleState, OriginalValuesKnown},
1220        test_utils::TrieTestHarness,
1221        updates::TrieUpdates,
1222        HashedPostState, HashedStorage, MultiProofTargetsV2, SortedTrieData,
1223    };
1224    use std::{
1225        collections::{BTreeMap, HashMap},
1226        ops::{Bound, Range, RangeBounds},
1227        sync::Arc,
1228    };
1229
1230    #[test]
1231    fn historical_proofs_complete_masked_trie_rows() -> eyre::Result<()> {
1232        use crate::{StaticFileProviderFactory, StaticFileSegment, StaticFileWriter};
1233
1234        let address = Address::with_last_byte(1);
1235        let other_address = Address::with_last_byte(2);
1236        let hashed_address = keccak256(address);
1237        let account = Account { balance: U256::ONE, ..Default::default() };
1238        // Branches 00, 01 and 02 share the cached row at 0. The first two change
1239        // in different blocks; the third keeps proof-v2's branch-collapse path inactive.
1240        let slots: Vec<B256> = (0..=2u8)
1241            .flat_map(|prefix| {
1242                (0..u64::MAX)
1243                    .map(|slot| B256::from(U256::from(slot)))
1244                    .filter(move |slot| keccak256(slot)[0] == prefix)
1245                    .take(2)
1246            })
1247            .collect();
1248        let mut storage: BTreeMap<_, _> = slots.iter().map(|&slot| (slot, U256::ONE)).collect();
1249        let mut trie = TrieTestHarness::new(
1250            storage.iter().map(|(slot, value)| (keccak256(slot), *value)).collect(),
1251        );
1252        let mut blocks = Vec::<ExecutedBlock>::new();
1253        let mut storage_roots = Vec::new();
1254        for number in 0..=2 {
1255            let mut output = (*ExecutedBlock::<reth_ethereum_primitives::EthPrimitives>::default()
1256                .execution_output)
1257                .clone();
1258            let (state, storage_updates) = if number == 0 {
1259                (
1260                    HashedPostState::default()
1261                        .with_accounts([
1262                            (hashed_address, Some(account.clone())),
1263                            (keccak256(other_address), Some(account.clone())),
1264                        ])
1265                        .with_storages([(
1266                            hashed_address,
1267                            HashedStorage::from_iter(trie.storage().iter().map(|(k, v)| (*k, *v))),
1268                        )]),
1269                    trie.storage_trie_updates().clone(),
1270                )
1271            } else {
1272                let slot = slots[(number as usize - 1) * 2];
1273                let value = U256::from(number + 1);
1274                let changes = BTreeMap::from([(keccak256(slot), value)]);
1275                let (_, updates) = trie.get_root_with_updates(&changes);
1276                trie.apply_changeset(changes);
1277                storage.insert(slot, value);
1278                let info = AccountInfo::default().with_balance(account.balance);
1279                output.state = BundleState::builder(number..=number)
1280                    .state_original_account_info(address, info.clone())
1281                    .state_present_account_info(address, info)
1282                    .state_storage(
1283                        address,
1284                        std::iter::once((U256::from_be_bytes(slot.0), (U256::ONE, value)))
1285                            .collect(),
1286                    )
1287                    .revert_storage(number, address, vec![(U256::from_be_bytes(slot.0), U256::ONE)])
1288                    .build();
1289                (
1290                    HashedPostState::from_hashed_storage(
1291                        hashed_address,
1292                        HashedStorage::from_iter([(keccak256(slot), value)]),
1293                    ),
1294                    updates,
1295                )
1296            };
1297            let mut updates = TrieUpdates::default();
1298            updates.storage_tries.insert(hashed_address, storage_updates);
1299            let state_root = reth_trie::test_utils::state_root([
1300                (address, (account.clone(), storage.clone())),
1301                (other_address, (account.clone(), BTreeMap::new())),
1302            ]);
1303            storage_roots.push(reth_trie::test_utils::storage_root(storage.clone()));
1304            let block = Block {
1305                header: alloy_consensus::Header {
1306                    number,
1307                    parent_hash: blocks
1308                        .last()
1309                        .map(|b| b.recovered_block().hash())
1310                        .unwrap_or_default(),
1311                    state_root,
1312                    ..Default::default()
1313                },
1314                ..Default::default()
1315            };
1316            blocks.push(ExecutedBlock::new(
1317                Arc::new(RecoveredBlock::new_unhashed(block, vec![])),
1318                Arc::new(output),
1319                SortedTrieData::new(Arc::new(state.into_sorted()), Arc::new(updates.into_sorted())),
1320            ));
1321        }
1322
1323        let factory = create_test_provider_factory();
1324        factory.set_storage_settings_cache(StorageSettings::v2());
1325        let writer = factory.provider_rw()?;
1326        writer.insert_block(blocks[0].recovered_block())?;
1327        writer.write_hashed_state(blocks[0].hashed_state_ref())?;
1328        writer.write_trie_updates_sorted(blocks[0].trie_updates_ref())?;
1329        writer.commit()?;
1330        let static_files = factory.static_file_provider();
1331        static_files.get_writer(0, StaticFileSegment::Receipts)?.increment_block(0)?;
1332        static_files
1333            .get_writer(0, StaticFileSegment::AccountChangeSets)?
1334            .append_account_changeset(vec![], 0)?;
1335        static_files
1336            .get_writer(0, StaticFileSegment::StorageChangeSets)?
1337            .append_storage_changeset(vec![], 0)?;
1338        static_files.commit()?;
1339        let writer = factory.provider_rw()?;
1340        writer.save_blocks(&SaveBlocksInput::new(blocks[1..].to_vec(), 0, 0, 2, 1))?;
1341        writer.commit()?;
1342        let provider = BlockchainProvider::new(factory)?;
1343        provider.canonical_in_memory_state.insert_executed(blocks[2].clone());
1344
1345        for number in [1, 2] {
1346            let state = provider.history_by_block_hash(blocks[number].recovered_block().hash())?;
1347            let root = blocks[number].recovered_block().state_root;
1348            state
1349                .multiproof_v2(
1350                    MultiProofTargetsV2 {
1351                        account_targets: vec![keccak256(other_address).into()],
1352                        ..Default::default()
1353                    },
1354                    false,
1355                )?
1356                .account_proof(other_address, &[])?
1357                .verify(root)?;
1358            assert_eq!(state.state_root(HashedPostState::default())?, root);
1359            assert_eq!(
1360                state.storage_root(address, HashedStorage::default())?,
1361                storage_roots[number]
1362            );
1363            state
1364                .storage_proof(address, slots[2], HashedStorage::default())?
1365                .verify(storage_roots[number])?;
1366            let proof = state.storage_multiproof(address, &[slots[2]], HashedStorage::default())?;
1367            assert_eq!(proof.root, storage_roots[number]);
1368            proof.storage_proof(slots[2])?.verify(storage_roots[number])?;
1369        }
1370        Ok(())
1371    }
1372
1373    const TEST_BLOCKS_COUNT: usize = 5;
1374
1375    const TEST_TRANSACTIONS_COUNT: u8 = 4;
1376
1377    fn random_blocks(
1378        rng: &mut impl Rng,
1379        database_blocks: usize,
1380        in_memory_blocks: usize,
1381        requests_count: Option<Range<u8>>,
1382        withdrawals_count: Option<Range<u8>>,
1383        tx_count: impl RangeBounds<u8>,
1384    ) -> (Vec<SealedBlock<Block>>, Vec<SealedBlock<Block>>) {
1385        let block_range = (database_blocks + in_memory_blocks - 1) as u64;
1386
1387        let tx_start = match tx_count.start_bound() {
1388            Bound::Included(&n) | Bound::Excluded(&n) => n,
1389            Bound::Unbounded => u8::MIN,
1390        };
1391        let tx_end = match tx_count.end_bound() {
1392            Bound::Included(&n) | Bound::Excluded(&n) => n + 1,
1393            Bound::Unbounded => u8::MAX,
1394        };
1395
1396        let blocks = random_block_range(
1397            rng,
1398            0..=block_range,
1399            BlockRangeParams {
1400                parent: Some(B256::ZERO),
1401                tx_count: tx_start..tx_end,
1402                requests_count,
1403                withdrawals_count,
1404            },
1405        );
1406        let (database_blocks, in_memory_blocks) = blocks.split_at(database_blocks);
1407        (database_blocks.to_vec(), in_memory_blocks.to_vec())
1408    }
1409
1410    #[expect(clippy::type_complexity)]
1411    fn provider_with_chain_spec_and_random_blocks(
1412        rng: &mut impl Rng,
1413        chain_spec: Arc<ChainSpec>,
1414        database_blocks: usize,
1415        in_memory_blocks: usize,
1416        block_range_params: BlockRangeParams,
1417    ) -> eyre::Result<(
1418        BlockchainProvider<MockNodeTypesWithDB>,
1419        Vec<SealedBlock<Block>>,
1420        Vec<SealedBlock<Block>>,
1421        Vec<Vec<Receipt>>,
1422    )> {
1423        let (database_blocks, in_memory_blocks) = random_blocks(
1424            rng,
1425            database_blocks,
1426            in_memory_blocks,
1427            block_range_params.requests_count,
1428            block_range_params.withdrawals_count,
1429            block_range_params.tx_count,
1430        );
1431
1432        let receipts: Vec<Vec<_>> = database_blocks
1433            .iter()
1434            .chain(in_memory_blocks.iter())
1435            .map(|block| block.body().transactions.iter())
1436            .map(|tx| tx.map(|tx| random_receipt(rng, tx, Some(2), None)).collect())
1437            .collect();
1438
1439        let factory = create_test_provider_factory_with_chain_spec(chain_spec);
1440        let provider_rw = factory.database_provider_rw()?;
1441
1442        // Insert blocks into the database
1443        for block in &database_blocks {
1444            provider_rw.insert_block(
1445                &block.clone().try_recover().expect("failed to seal block with senders"),
1446            )?;
1447        }
1448
1449        // Insert receipts into the database
1450        if let Some(first_block) = database_blocks.first() {
1451            provider_rw.write_state(
1452                &ExecutionOutcome {
1453                    first_block: first_block.number,
1454                    receipts: receipts.iter().take(database_blocks.len()).cloned().collect(),
1455                    ..Default::default()
1456                },
1457                OriginalValuesKnown::No,
1458                StateWriteConfig::default(),
1459            )?;
1460        }
1461
1462        provider_rw.commit()?;
1463
1464        let provider = BlockchainProvider::new(factory)?;
1465
1466        // Insert the rest of the blocks and receipts into the in-memory state
1467        let chain = NewCanonicalChain::Commit {
1468            new: in_memory_blocks
1469                .iter()
1470                .map(|block| {
1471                    let senders = block.senders().expect("failed to recover senders");
1472                    let block_receipts = receipts.get(block.number as usize).unwrap().clone();
1473                    let execution_outcome = BlockExecutionOutput {
1474                        result: BlockExecutionResult {
1475                            receipts: block_receipts,
1476                            requests: Default::default(),
1477                            gas_used: 0,
1478                            blob_gas_used: 0,
1479                        },
1480                        state: BundleState::default(),
1481                    };
1482
1483                    ExecutedBlock {
1484                        recovered_block: Arc::new(RecoveredBlock::new_sealed(
1485                            block.clone(),
1486                            senders,
1487                        )),
1488                        execution_output: execution_outcome.into(),
1489                        ..Default::default()
1490                    }
1491                })
1492                .collect(),
1493        };
1494        if !in_memory_blocks.is_empty() {
1495            provider.canonical_in_memory_state.update_chain(chain);
1496        }
1497
1498        // Get canonical, safe, and finalized blocks
1499        let blocks = database_blocks.iter().chain(in_memory_blocks.iter()).collect::<Vec<_>>();
1500        let block_count = blocks.len();
1501        let canonical_block = blocks.get(block_count - 1).unwrap();
1502        let safe_block = blocks.get(block_count - 2).unwrap();
1503        let finalized_block = blocks.get(block_count - 3).unwrap();
1504
1505        // Set the canonical head, safe, and finalized blocks
1506        provider.set_canonical_head(canonical_block.clone_sealed_header());
1507        provider.set_safe(safe_block.clone_sealed_header());
1508        provider.set_finalized(finalized_block.clone_sealed_header());
1509
1510        Ok((provider, database_blocks.clone(), in_memory_blocks.clone(), receipts))
1511    }
1512
1513    #[expect(clippy::type_complexity)]
1514    fn provider_with_random_blocks(
1515        rng: &mut impl Rng,
1516        database_blocks: usize,
1517        in_memory_blocks: usize,
1518        block_range_params: BlockRangeParams,
1519    ) -> eyre::Result<(
1520        BlockchainProvider<MockNodeTypesWithDB>,
1521        Vec<SealedBlock<Block>>,
1522        Vec<SealedBlock<Block>>,
1523        Vec<Vec<Receipt>>,
1524    )> {
1525        provider_with_chain_spec_and_random_blocks(
1526            rng,
1527            MAINNET.clone(),
1528            database_blocks,
1529            in_memory_blocks,
1530            block_range_params,
1531        )
1532    }
1533
1534    /// This will persist the last block in-memory and delete it from
1535    /// `canonical_in_memory_state` right after a database read transaction is created.
1536    ///
1537    /// This simulates a RPC method having a different view than when its database transaction was
1538    /// created.
1539    fn persist_block_after_db_tx_creation(
1540        provider: BlockchainProvider<MockNodeTypesWithDB>,
1541        block_number: BlockNumber,
1542    ) {
1543        let hook_provider = provider.clone();
1544        provider.database.db_ref().set_post_transaction_hook(Box::new(move || {
1545            if let Some(state) = hook_provider.canonical_in_memory_state.head_state() &&
1546                state.anchor().number + 1 == block_number
1547            {
1548                let mut lowest_memory_block =
1549                    state.parent_state_chain().last().expect("qed").block();
1550                let num_hash = lowest_memory_block.recovered_block().num_hash();
1551
1552                let execution_output = (*lowest_memory_block.execution_output).clone();
1553                lowest_memory_block.execution_output = Arc::new(execution_output);
1554
1555                // Push to disk
1556                let provider_rw = hook_provider.database_provider_rw().unwrap();
1557                let input = SaveBlocksInput::new(
1558                    vec![lowest_memory_block],
1559                    state.anchor().number,
1560                    state.anchor().number,
1561                    block_number,
1562                    block_number,
1563                );
1564                provider_rw.save_blocks(&input).unwrap();
1565                provider_rw.commit().unwrap();
1566
1567                // Remove from memory
1568                hook_provider.canonical_in_memory_state.remove_persisted_blocks(num_hash);
1569            }
1570        }));
1571    }
1572
1573    #[test]
1574    fn test_block_reader_find_block_by_hash() -> eyre::Result<()> {
1575        // Initialize random number generator and provider factory
1576        let mut rng = generators::rng();
1577        let factory = create_test_provider_factory();
1578
1579        // Generate 10 random blocks and split into database and in-memory blocks
1580        let blocks = random_block_range(
1581            &mut rng,
1582            0..=10,
1583            BlockRangeParams { parent: Some(B256::ZERO), tx_count: 0..1, ..Default::default() },
1584        );
1585        let (database_blocks, in_memory_blocks) = blocks.split_at(5);
1586
1587        // Insert first 5 blocks into the database
1588        let provider_rw = factory.provider_rw()?;
1589        for block in database_blocks {
1590            provider_rw.insert_block(
1591                &block.clone().try_recover().expect("failed to seal block with senders"),
1592            )?;
1593        }
1594
1595        provider_rw.commit()?;
1596
1597        // Create a new provider
1598        let provider = BlockchainProvider::new(factory)?;
1599
1600        // Useful blocks
1601        let first_db_block = database_blocks.first().unwrap();
1602        let first_in_mem_block = in_memory_blocks.first().unwrap();
1603        let last_in_mem_block = in_memory_blocks.last().unwrap();
1604
1605        // No block in memory before setting in memory state
1606        assert_eq!(provider.find_block_by_hash(first_in_mem_block.hash(), BlockSource::Any)?, None);
1607        assert_eq!(
1608            provider.find_block_by_hash(first_in_mem_block.hash(), BlockSource::Canonical)?,
1609            None
1610        );
1611        // No pending block in memory
1612        assert_eq!(
1613            provider.find_block_by_hash(first_in_mem_block.hash(), BlockSource::Pending)?,
1614            None
1615        );
1616
1617        // Insert first block into the in-memory state
1618        let in_memory_block_senders =
1619            first_in_mem_block.senders().expect("failed to recover senders");
1620        let chain = NewCanonicalChain::Commit {
1621            new: vec![ExecutedBlock {
1622                recovered_block: Arc::new(RecoveredBlock::new_sealed(
1623                    first_in_mem_block.clone(),
1624                    in_memory_block_senders,
1625                )),
1626                ..Default::default()
1627            }],
1628        };
1629        provider.canonical_in_memory_state.update_chain(chain);
1630
1631        // Now the block should be found in memory
1632        assert_eq!(
1633            provider.find_block_by_hash(first_in_mem_block.hash(), BlockSource::Any)?,
1634            Some(first_in_mem_block.clone().into_block())
1635        );
1636        assert_eq!(
1637            provider.find_block_by_hash(first_in_mem_block.hash(), BlockSource::Canonical)?,
1638            Some(first_in_mem_block.clone().into_block())
1639        );
1640
1641        // Find the first block in database by hash
1642        assert_eq!(
1643            provider.find_block_by_hash(first_db_block.hash(), BlockSource::Any)?,
1644            Some(first_db_block.clone().into_block())
1645        );
1646        assert_eq!(
1647            provider.find_block_by_hash(first_db_block.hash(), BlockSource::Canonical)?,
1648            Some(first_db_block.clone().into_block())
1649        );
1650
1651        // No pending block in database
1652        assert_eq!(provider.find_block_by_hash(first_db_block.hash(), BlockSource::Pending)?, None);
1653
1654        // Insert the last block into the pending state
1655        provider.canonical_in_memory_state.set_pending_block(ExecutedBlock {
1656            recovered_block: Arc::new(RecoveredBlock::new_sealed(
1657                last_in_mem_block.clone(),
1658                Default::default(),
1659            )),
1660            ..Default::default()
1661        });
1662
1663        // Now the last block should be found in memory
1664        assert_eq!(
1665            provider.find_block_by_hash(last_in_mem_block.hash(), BlockSource::Pending)?,
1666            Some(last_in_mem_block.clone().into_block())
1667        );
1668
1669        Ok(())
1670    }
1671
1672    #[test]
1673    fn test_block_reader_block() -> eyre::Result<()> {
1674        // Initialize random number generator and provider factory
1675        let mut rng = generators::rng();
1676        let factory = create_test_provider_factory();
1677
1678        // Generate 10 random blocks and split into database and in-memory blocks
1679        let blocks = random_block_range(
1680            &mut rng,
1681            0..=10,
1682            BlockRangeParams { parent: Some(B256::ZERO), tx_count: 0..1, ..Default::default() },
1683        );
1684        let (database_blocks, in_memory_blocks) = blocks.split_at(5);
1685
1686        // Insert first 5 blocks into the database
1687        let provider_rw = factory.provider_rw()?;
1688        for block in database_blocks {
1689            provider_rw.insert_block(
1690                &block.clone().try_recover().expect("failed to seal block with senders"),
1691            )?;
1692        }
1693        provider_rw.commit()?;
1694
1695        // Create a new provider
1696        let provider = BlockchainProvider::new(factory)?;
1697
1698        // First in memory block
1699        let first_in_mem_block = in_memory_blocks.first().unwrap();
1700        // First database block
1701        let first_db_block = database_blocks.first().unwrap();
1702
1703        // First in memory block should not be found yet as not integrated to the in-memory state
1704        assert_eq!(provider.block(BlockHashOrNumber::Hash(first_in_mem_block.hash()))?, None);
1705        assert_eq!(provider.block(BlockHashOrNumber::Number(first_in_mem_block.number))?, None);
1706
1707        // Insert first block into the in-memory state
1708        let in_memory_block_senders =
1709            first_in_mem_block.senders().expect("failed to recover senders");
1710        let chain = NewCanonicalChain::Commit {
1711            new: vec![ExecutedBlock {
1712                recovered_block: Arc::new(RecoveredBlock::new_sealed(
1713                    first_in_mem_block.clone(),
1714                    in_memory_block_senders,
1715                )),
1716                ..Default::default()
1717            }],
1718        };
1719        provider.canonical_in_memory_state.update_chain(chain);
1720
1721        // First in memory block should be found
1722        assert_eq!(
1723            provider.block(BlockHashOrNumber::Hash(first_in_mem_block.hash()))?,
1724            Some(first_in_mem_block.clone().into_block())
1725        );
1726        assert_eq!(
1727            provider.block(BlockHashOrNumber::Number(first_in_mem_block.number))?,
1728            Some(first_in_mem_block.clone().into_block())
1729        );
1730
1731        // First database block should be found
1732        assert_eq!(
1733            provider.block(BlockHashOrNumber::Hash(first_db_block.hash()))?,
1734            Some(first_db_block.clone().into_block())
1735        );
1736        assert_eq!(
1737            provider.block(BlockHashOrNumber::Number(first_db_block.number))?,
1738            Some(first_db_block.clone().into_block())
1739        );
1740
1741        Ok(())
1742    }
1743
1744    #[test]
1745    fn test_block_reader_pending_block() -> eyre::Result<()> {
1746        let mut rng = generators::rng();
1747        let (provider, _, _, _) = provider_with_random_blocks(
1748            &mut rng,
1749            TEST_BLOCKS_COUNT,
1750            TEST_BLOCKS_COUNT,
1751            BlockRangeParams::default(),
1752        )?;
1753
1754        // Generate a random block
1755        let mut rng = generators::rng();
1756        let block = random_block(
1757            &mut rng,
1758            0,
1759            BlockParams { parent: Some(B256::ZERO), ..Default::default() },
1760        );
1761
1762        // Set the block as pending
1763        provider.canonical_in_memory_state.set_pending_block(ExecutedBlock {
1764            recovered_block: Arc::new(RecoveredBlock::new_sealed(
1765                block.clone(),
1766                block.senders().unwrap(),
1767            )),
1768            ..Default::default()
1769        });
1770
1771        // Assertions related to the pending block
1772
1773        let pending_block = provider.pending_block()?.unwrap();
1774        assert_eq!(
1775            *pending_block,
1776            RecoveredBlock::new_sealed(block.clone(), block.senders().unwrap())
1777        );
1778
1779        let pending = provider.pending_block_and_receipts()?.unwrap();
1780        assert!(Arc::ptr_eq(&pending_block, pending.block()));
1781        assert!(pending.execution_output().receipts.is_empty());
1782
1783        Ok(())
1784    }
1785
1786    #[test]
1787    fn test_block_reader_side_chain_block_by_hash() -> eyre::Result<()> {
1788        let mut rng = generators::rng();
1789        let (provider, _, in_memory_blocks, _) = provider_with_random_blocks(
1790            &mut rng,
1791            TEST_BLOCKS_COUNT,
1792            TEST_BLOCKS_COUNT,
1793            BlockRangeParams::default(),
1794        )?;
1795
1796        // A fork of the first in-memory block that the engine tree holds but is not canonical.
1797        let canonical = in_memory_blocks.first().unwrap();
1798        let fork = random_block(
1799            &mut rng,
1800            canonical.number,
1801            BlockParams { parent: Some(canonical.parent_hash), ..Default::default() },
1802        );
1803        let fork_hash = fork.hash();
1804        let recovered = RecoveredBlock::new_sealed(fork.clone(), fork.senders().unwrap());
1805        let bal = Bytes::from_static(&[0xc2, 0xc0, 0xc0]);
1806        provider.canonical_in_memory_state.insert_executed(
1807            ExecutedBlock { recovered_block: Arc::new(recovered.clone()), ..Default::default() }
1808                .with_bal(Some(Arc::new(DecodedEvmBal::new(Arc::default(), bal.clone())))),
1809        );
1810
1811        assert_eq!(provider.block(fork_hash.into())?, Some(fork.into_block()));
1812        assert_eq!(
1813            provider.recovered_block(fork_hash.into(), TransactionVariant::WithHash)?,
1814            Some(recovered.clone())
1815        );
1816        assert_eq!(
1817            provider.sealed_block_with_senders(fork_hash.into(), TransactionVariant::WithHash)?,
1818            Some(recovered)
1819        );
1820        assert_eq!(provider.get_bal_by_hash(fork_hash)?, Some(bal.clone()));
1821        assert_eq!(provider.get_bals_by_hashes(&[fork_hash])?, vec![Some(bal.clone())]);
1822        // The store counts each missing BAL as one byte, the filled BAL exceeds the limit.
1823        assert_eq!(
1824            provider.get_bals_by_hashes_with_limit(
1825                &[fork_hash, fork_hash],
1826                GetBlockAccessListLimit::ResponseSizeSoftLimit(2)
1827            )?,
1828            vec![Some(bal)]
1829        );
1830
1831        // Canonical lookups still only see the canonical chain.
1832        assert_eq!(provider.block(canonical.number.into())?, Some(canonical.clone().into_block()));
1833        assert_eq!(provider.block_number(fork_hash)?, None);
1834        let fork_canonical_id = BlockId::hash_canonical(fork_hash);
1835        assert_eq!(provider.block_by_id(fork_canonical_id)?, None);
1836        assert_eq!(provider.block_hash_for_id(fork_canonical_id)?, None);
1837        assert_eq!(
1838            provider.block_with_senders_by_id(fork_canonical_id, TransactionVariant::WithHash)?,
1839            None
1840        );
1841        assert_eq!(
1842            provider.block_hash_for_id(BlockId::hash_canonical(canonical.hash()))?,
1843            Some(canonical.hash())
1844        );
1845
1846        // Once the fork is dropped, its hash is unknown again.
1847        provider.canonical_in_memory_state.prune_conflicting_with_finalized(canonical.num_hash());
1848        assert_eq!(provider.block(fork_hash.into())?, None);
1849        assert_eq!(provider.get_bals_by_hashes(&[fork_hash])?, vec![None]);
1850
1851        Ok(())
1852    }
1853
1854    #[test]
1855    fn test_block_body_indices() -> eyre::Result<()> {
1856        // Create a new provider
1857        let mut rng = generators::rng();
1858        let (provider, database_blocks, in_memory_blocks, _) = provider_with_random_blocks(
1859            &mut rng,
1860            TEST_BLOCKS_COUNT,
1861            TEST_BLOCKS_COUNT,
1862            BlockRangeParams {
1863                tx_count: TEST_TRANSACTIONS_COUNT..TEST_TRANSACTIONS_COUNT,
1864                ..Default::default()
1865            },
1866        )?;
1867
1868        let first_in_mem_block = in_memory_blocks.first().unwrap();
1869
1870        // Insert the first block into the in-memory state
1871        let in_memory_block_senders =
1872            first_in_mem_block.senders().expect("failed to recover senders");
1873        let chain = NewCanonicalChain::Commit {
1874            new: vec![ExecutedBlock {
1875                recovered_block: Arc::new(RecoveredBlock::new_sealed(
1876                    first_in_mem_block.clone(),
1877                    in_memory_block_senders,
1878                )),
1879                ..Default::default()
1880            }],
1881        };
1882        provider.canonical_in_memory_state.update_chain(chain);
1883
1884        let first_db_block = database_blocks.first().unwrap().clone();
1885        let first_in_mem_block = in_memory_blocks.first().unwrap().clone();
1886
1887        // First database block body indices should be found
1888        assert_eq!(
1889            provider.block_body_indices(first_db_block.number)?.unwrap(),
1890            StoredBlockBodyIndices { first_tx_num: 0, tx_count: 4 }
1891        );
1892
1893        // First in-memory block body indices should be found with the first tx after the database
1894        // blocks
1895        assert_eq!(
1896            provider.block_body_indices(first_in_mem_block.number)?.unwrap(),
1897            StoredBlockBodyIndices { first_tx_num: 20, tx_count: 4 }
1898        );
1899
1900        // A random block number should return None as the block is not found
1901        let mut rng = rand::rng();
1902        let random_block_number: u64 = rng.random();
1903        assert_eq!(provider.block_body_indices(random_block_number)?, None);
1904
1905        Ok(())
1906    }
1907
1908    #[test]
1909    fn test_block_hash_reader() -> eyre::Result<()> {
1910        let mut rng = generators::rng();
1911        let (provider, database_blocks, in_memory_blocks, _) = provider_with_random_blocks(
1912            &mut rng,
1913            TEST_BLOCKS_COUNT,
1914            TEST_BLOCKS_COUNT,
1915            BlockRangeParams::default(),
1916        )?;
1917
1918        let database_block = database_blocks.first().unwrap().clone();
1919        let in_memory_block = in_memory_blocks.last().unwrap().clone();
1920
1921        assert_eq!(provider.block_hash(database_block.number)?, Some(database_block.hash()));
1922        assert_eq!(provider.block_hash(in_memory_block.number)?, Some(in_memory_block.hash()));
1923
1924        assert_eq!(
1925            provider.canonical_hashes_range(0, 10)?,
1926            [database_blocks, in_memory_blocks]
1927                .concat()
1928                .iter()
1929                .map(|block| block.hash())
1930                .collect::<Vec<_>>()
1931        );
1932
1933        Ok(())
1934    }
1935
1936    #[test]
1937    fn test_header_provider() -> eyre::Result<()> {
1938        let mut rng = generators::rng();
1939        let (provider, database_blocks, in_memory_blocks, _) = provider_with_random_blocks(
1940            &mut rng,
1941            TEST_BLOCKS_COUNT,
1942            TEST_BLOCKS_COUNT,
1943            BlockRangeParams::default(),
1944        )?;
1945
1946        // make sure that the finalized block is on db
1947        let finalized_block = database_blocks.get(database_blocks.len() - 3).unwrap();
1948        provider.set_finalized(finalized_block.clone_sealed_header());
1949
1950        let blocks = [database_blocks, in_memory_blocks].concat();
1951
1952        assert_eq!(
1953            provider.sealed_headers_while(0..=10, |header| header.number <= 8)?,
1954            blocks
1955                .iter()
1956                .take_while(|header| header.number <= 8)
1957                .map(|b| b.clone_sealed_header())
1958                .collect::<Vec<_>>()
1959        );
1960
1961        Ok(())
1962    }
1963
1964    #[tokio::test]
1965    async fn test_canon_state_subscriptions() -> eyre::Result<()> {
1966        let factory = create_test_provider_factory();
1967
1968        // Generate a random block to initialize the blockchain provider.
1969        let mut test_block_builder = TestBlockBuilder::eth();
1970        let block_1 = test_block_builder.generate_random_block(0, B256::ZERO).try_recover()?;
1971        let block_hash_1 = block_1.hash();
1972
1973        // Insert and commit the block.
1974        let provider_rw = factory.provider_rw()?;
1975        provider_rw.insert_block(&block_1)?;
1976        provider_rw.commit()?;
1977
1978        let provider = BlockchainProvider::new(factory)?;
1979
1980        // Subscribe twice for canonical state updates.
1981        let in_memory_state = provider.canonical_in_memory_state();
1982        let mut rx_1 = provider.subscribe_to_canonical_state();
1983        let mut rx_2 = provider.subscribe_to_canonical_state();
1984
1985        // Send and receive commit notifications.
1986        let block_2 = test_block_builder.generate_random_block(1, block_hash_1).try_recover()?;
1987        let chain = Chain::new(vec![block_2], ExecutionOutcome::default(), BTreeMap::new());
1988        let commit = CanonStateNotification::Commit { new: Arc::new(chain.clone()) };
1989        in_memory_state.notify_canon_state(commit.clone());
1990        let (notification_1, notification_2) = tokio::join!(rx_1.recv(), rx_2.recv());
1991        assert_eq!(notification_1, Ok(commit.clone()));
1992        assert_eq!(notification_2, Ok(commit.clone()));
1993
1994        // Send and receive re-org notifications.
1995        let block_3 = test_block_builder.generate_random_block(1, block_hash_1).try_recover()?;
1996        let block_4 = test_block_builder.generate_random_block(2, block_3.hash()).try_recover()?;
1997        let new_chain =
1998            Chain::new(vec![block_3, block_4], ExecutionOutcome::default(), BTreeMap::new());
1999        let re_org =
2000            CanonStateNotification::Reorg { old: Arc::new(chain), new: Arc::new(new_chain) };
2001        in_memory_state.notify_canon_state(re_org.clone());
2002        let (notification_1, notification_2) = tokio::join!(rx_1.recv(), rx_2.recv());
2003        assert_eq!(notification_1, Ok(re_org.clone()));
2004        assert_eq!(notification_2, Ok(re_org.clone()));
2005
2006        Ok(())
2007    }
2008
2009    #[test]
2010    fn test_block_num_reader() -> eyre::Result<()> {
2011        let mut rng = generators::rng();
2012        let (provider, database_blocks, in_memory_blocks, _) = provider_with_random_blocks(
2013            &mut rng,
2014            TEST_BLOCKS_COUNT,
2015            TEST_BLOCKS_COUNT,
2016            BlockRangeParams::default(),
2017        )?;
2018
2019        assert_eq!(provider.best_block_number()?, in_memory_blocks.last().unwrap().number);
2020        assert_eq!(provider.last_block_number()?, database_blocks.last().unwrap().number);
2021
2022        let database_block = database_blocks.first().unwrap().clone();
2023        let in_memory_block = in_memory_blocks.first().unwrap().clone();
2024        assert_eq!(provider.block_number(database_block.hash())?, Some(database_block.number));
2025        assert_eq!(provider.block_number(in_memory_block.hash())?, Some(in_memory_block.number));
2026
2027        Ok(())
2028    }
2029
2030    #[test]
2031    fn test_block_reader_id_ext_block_by_id() -> eyre::Result<()> {
2032        let mut rng = generators::rng();
2033        let (provider, database_blocks, in_memory_blocks, _) = provider_with_random_blocks(
2034            &mut rng,
2035            TEST_BLOCKS_COUNT,
2036            TEST_BLOCKS_COUNT,
2037            BlockRangeParams::default(),
2038        )?;
2039
2040        let database_block = database_blocks.first().unwrap().clone();
2041        let in_memory_block = in_memory_blocks.last().unwrap().clone();
2042
2043        let block_number = database_block.number;
2044        let block_hash = database_block.hash();
2045
2046        assert_eq!(
2047            provider.block_by_id(block_number.into()).unwrap(),
2048            Some(database_block.clone().into_block())
2049        );
2050        assert_eq!(
2051            provider.block_by_id(block_hash.into()).unwrap(),
2052            Some(database_block.into_block())
2053        );
2054
2055        let block_number = in_memory_block.number;
2056        let block_hash = in_memory_block.hash();
2057        assert_eq!(
2058            provider.block_by_id(block_number.into()).unwrap(),
2059            Some(in_memory_block.clone().into_block())
2060        );
2061        assert_eq!(
2062            provider.block_by_id(block_hash.into()).unwrap(),
2063            Some(in_memory_block.into_block())
2064        );
2065
2066        Ok(())
2067    }
2068
2069    #[test]
2070    fn test_block_reader_id_ext_header_by_number_or_tag() -> eyre::Result<()> {
2071        let mut rng = generators::rng();
2072        let (provider, database_blocks, in_memory_blocks, _) = provider_with_random_blocks(
2073            &mut rng,
2074            TEST_BLOCKS_COUNT,
2075            TEST_BLOCKS_COUNT,
2076            BlockRangeParams::default(),
2077        )?;
2078
2079        let database_block = database_blocks.first().unwrap().clone();
2080
2081        let in_memory_block_count = in_memory_blocks.len();
2082        let canonical_block = in_memory_blocks.get(in_memory_block_count - 1).unwrap().clone();
2083        let safe_block = in_memory_blocks.get(in_memory_block_count - 2).unwrap().clone();
2084        let finalized_block = in_memory_blocks.get(in_memory_block_count - 3).unwrap().clone();
2085
2086        let block_number = database_block.number;
2087        assert_eq!(
2088            provider.header_by_number_or_tag(block_number.into()).unwrap(),
2089            Some(database_block.header().clone())
2090        );
2091        assert_eq!(
2092            provider.sealed_header_by_number_or_tag(block_number.into())?,
2093            Some(database_block.clone_sealed_header())
2094        );
2095
2096        assert_eq!(
2097            provider.header_by_number_or_tag(BlockNumberOrTag::Latest).unwrap(),
2098            Some(canonical_block.header().clone())
2099        );
2100        assert_eq!(
2101            provider.sealed_header_by_number_or_tag(BlockNumberOrTag::Latest).unwrap(),
2102            Some(canonical_block.clone_sealed_header())
2103        );
2104
2105        assert_eq!(
2106            provider.header_by_number_or_tag(BlockNumberOrTag::Safe).unwrap(),
2107            Some(safe_block.header().clone())
2108        );
2109        assert_eq!(
2110            provider.sealed_header_by_number_or_tag(BlockNumberOrTag::Safe).unwrap(),
2111            Some(safe_block.clone_sealed_header())
2112        );
2113
2114        assert_eq!(
2115            provider.header_by_number_or_tag(BlockNumberOrTag::Finalized).unwrap(),
2116            Some(finalized_block.header().clone())
2117        );
2118        assert_eq!(
2119            provider.sealed_header_by_number_or_tag(BlockNumberOrTag::Finalized).unwrap(),
2120            Some(finalized_block.clone_sealed_header())
2121        );
2122
2123        assert_eq!(
2124            provider.header_by_number_or_tag(BlockNumberOrTag::Earliest).unwrap(),
2125            Some(database_block.header().clone())
2126        );
2127        assert_eq!(
2128            provider.sealed_header_by_number_or_tag(BlockNumberOrTag::Earliest).unwrap(),
2129            Some(database_block.clone_sealed_header())
2130        );
2131
2132        assert_eq!(provider.header_by_number_or_tag(BlockNumberOrTag::Pending)?, None);
2133        assert_eq!(provider.sealed_header_by_number_or_tag(BlockNumberOrTag::Pending)?, None);
2134        let pending_block = random_block(
2135            &mut rng,
2136            canonical_block.number + 1,
2137            BlockParams { parent: Some(canonical_block.hash()), ..Default::default() },
2138        );
2139        provider.canonical_in_memory_state.set_pending_block(ExecutedBlock {
2140            recovered_block: Arc::new(RecoveredBlock::new_sealed(
2141                pending_block.clone(),
2142                pending_block.senders().unwrap(),
2143            )),
2144            ..Default::default()
2145        });
2146        assert_eq!(
2147            provider.header_by_number_or_tag(BlockNumberOrTag::Pending).unwrap(),
2148            Some(pending_block.header().clone())
2149        );
2150        assert_eq!(
2151            provider.sealed_header_by_number_or_tag(BlockNumberOrTag::Pending).unwrap(),
2152            Some(pending_block.clone_sealed_header())
2153        );
2154
2155        Ok(())
2156    }
2157
2158    #[test]
2159    fn test_block_reader_id_ext_header_by_id() -> eyre::Result<()> {
2160        let mut rng = generators::rng();
2161        let (provider, database_blocks, in_memory_blocks, _) = provider_with_random_blocks(
2162            &mut rng,
2163            TEST_BLOCKS_COUNT,
2164            TEST_BLOCKS_COUNT,
2165            BlockRangeParams::default(),
2166        )?;
2167
2168        let database_block = database_blocks.first().unwrap().clone();
2169        let in_memory_block = in_memory_blocks.last().unwrap().clone();
2170
2171        let block_number = database_block.number;
2172        let block_hash = database_block.hash();
2173
2174        assert_eq!(
2175            provider.header_by_id(block_number.into()).unwrap(),
2176            Some(database_block.header().clone())
2177        );
2178        assert_eq!(
2179            provider.sealed_header_by_id(block_number.into()).unwrap(),
2180            Some(database_block.clone_sealed_header())
2181        );
2182
2183        assert_eq!(
2184            provider.header_by_id(block_hash.into()).unwrap(),
2185            Some(database_block.header().clone())
2186        );
2187        assert_eq!(
2188            provider.sealed_header_by_id(block_hash.into()).unwrap(),
2189            Some(database_block.clone_sealed_header())
2190        );
2191
2192        let block_number = in_memory_block.number;
2193        let block_hash = in_memory_block.hash();
2194
2195        assert_eq!(
2196            provider.header_by_id(block_number.into()).unwrap(),
2197            Some(in_memory_block.header().clone())
2198        );
2199        assert_eq!(
2200            provider.sealed_header_by_id(block_number.into()).unwrap(),
2201            Some(in_memory_block.clone_sealed_header())
2202        );
2203
2204        assert_eq!(
2205            provider.header_by_id(block_hash.into()).unwrap(),
2206            Some(in_memory_block.header().clone())
2207        );
2208        assert_eq!(
2209            provider.sealed_header_by_id(block_hash.into()).unwrap(),
2210            Some(in_memory_block.clone_sealed_header())
2211        );
2212
2213        let safe_block = in_memory_blocks[in_memory_blocks.len() - 2].clone();
2214        let finalized_block = in_memory_blocks[in_memory_blocks.len() - 3].clone();
2215        assert_eq!(
2216            provider.header_by_id(BlockNumberOrTag::Latest.into()).unwrap(),
2217            Some(in_memory_block.header().clone())
2218        );
2219        assert_eq!(
2220            provider.sealed_header_by_id(BlockNumberOrTag::Latest.into()).unwrap(),
2221            Some(in_memory_block.clone_sealed_header())
2222        );
2223        assert_eq!(
2224            provider.header_by_id(BlockNumberOrTag::Safe.into()).unwrap(),
2225            Some(safe_block.header().clone())
2226        );
2227        assert_eq!(
2228            provider.sealed_header_by_id(BlockNumberOrTag::Safe.into()).unwrap(),
2229            Some(safe_block.clone_sealed_header())
2230        );
2231        assert_eq!(
2232            provider.header_by_id(BlockNumberOrTag::Finalized.into()).unwrap(),
2233            Some(finalized_block.header().clone())
2234        );
2235        assert_eq!(
2236            provider.sealed_header_by_id(BlockNumberOrTag::Finalized.into()).unwrap(),
2237            Some(finalized_block.clone_sealed_header())
2238        );
2239        assert_eq!(
2240            provider.header_by_id(BlockNumberOrTag::Earliest.into()).unwrap(),
2241            Some(database_block.header().clone())
2242        );
2243        assert_eq!(
2244            provider.sealed_header_by_id(BlockNumberOrTag::Earliest.into()).unwrap(),
2245            Some(database_block.clone_sealed_header())
2246        );
2247
2248        assert_eq!(provider.header_by_id(BlockNumberOrTag::Pending.into())?, None);
2249        assert_eq!(provider.sealed_header_by_id(BlockNumberOrTag::Pending.into())?, None);
2250        let pending_block = random_block(
2251            &mut rng,
2252            in_memory_block.number + 1,
2253            BlockParams { parent: Some(in_memory_block.hash()), ..Default::default() },
2254        );
2255        provider.canonical_in_memory_state.set_pending_block(ExecutedBlock {
2256            recovered_block: Arc::new(RecoveredBlock::new_sealed(
2257                pending_block.clone(),
2258                pending_block.senders().unwrap(),
2259            )),
2260            ..Default::default()
2261        });
2262        assert_eq!(
2263            provider.header_by_id(BlockNumberOrTag::Pending.into()).unwrap(),
2264            Some(pending_block.header().clone())
2265        );
2266        assert_eq!(
2267            provider.sealed_header_by_id(BlockNumberOrTag::Pending.into()).unwrap(),
2268            Some(pending_block.clone_sealed_header())
2269        );
2270
2271        Ok(())
2272    }
2273
2274    #[test]
2275    fn test_receipt_provider_id_ext_receipts_by_block_id() -> eyre::Result<()> {
2276        let mut rng = generators::rng();
2277        let (provider, database_blocks, in_memory_blocks, receipts) = provider_with_random_blocks(
2278            &mut rng,
2279            TEST_BLOCKS_COUNT,
2280            TEST_BLOCKS_COUNT,
2281            BlockRangeParams { tx_count: 1..3, ..Default::default() },
2282        )?;
2283
2284        let database_block = database_blocks.first().unwrap().clone();
2285        let in_memory_block = in_memory_blocks.last().unwrap().clone();
2286
2287        let block_number = database_block.number;
2288        let block_hash = database_block.hash();
2289
2290        assert!(!receipts.get(database_block.number as usize).unwrap().is_empty());
2291        assert!(!provider
2292            .receipts_by_number_or_tag(database_block.number.into())?
2293            .unwrap()
2294            .is_empty());
2295
2296        assert_eq!(
2297            provider.receipts_by_block_id(block_number.into())?.unwrap(),
2298            receipts.get(block_number as usize).unwrap().clone()
2299        );
2300        assert_eq!(
2301            provider.receipts_by_block_id(block_hash.into())?.unwrap(),
2302            receipts.get(block_number as usize).unwrap().clone()
2303        );
2304
2305        let block_number = in_memory_block.number;
2306        let block_hash = in_memory_block.hash();
2307
2308        assert_eq!(
2309            provider.receipts_by_block_id(block_number.into())?.unwrap(),
2310            receipts.get(block_number as usize).unwrap().clone()
2311        );
2312        assert_eq!(
2313            provider.receipts_by_block_id(block_hash.into())?.unwrap(),
2314            receipts.get(block_number as usize).unwrap().clone()
2315        );
2316
2317        Ok(())
2318    }
2319
2320    #[test]
2321    fn test_receipt_provider_id_ext_receipts_by_block_number_or_tag() -> eyre::Result<()> {
2322        let mut rng = generators::rng();
2323        let (provider, database_blocks, in_memory_blocks, receipts) = provider_with_random_blocks(
2324            &mut rng,
2325            TEST_BLOCKS_COUNT,
2326            TEST_BLOCKS_COUNT,
2327            BlockRangeParams { tx_count: 1..3, ..Default::default() },
2328        )?;
2329
2330        let database_block = database_blocks.first().unwrap().clone();
2331
2332        let in_memory_block_count = in_memory_blocks.len();
2333        let canonical_block = in_memory_blocks.get(in_memory_block_count - 1).unwrap().clone();
2334        let safe_block = in_memory_blocks.get(in_memory_block_count - 2).unwrap().clone();
2335        let finalized_block = in_memory_blocks.get(in_memory_block_count - 3).unwrap().clone();
2336
2337        assert!(!receipts.get(database_block.number as usize).unwrap().is_empty());
2338        assert!(!provider
2339            .receipts_by_number_or_tag(database_block.number.into())?
2340            .unwrap()
2341            .is_empty());
2342
2343        assert_eq!(
2344            provider.receipts_by_number_or_tag(database_block.number.into())?.unwrap(),
2345            receipts.get(database_block.number as usize).unwrap().clone()
2346        );
2347        assert_eq!(
2348            provider.receipts_by_number_or_tag(BlockNumberOrTag::Latest)?.unwrap(),
2349            receipts.get(canonical_block.number as usize).unwrap().clone()
2350        );
2351        assert_eq!(
2352            provider.receipts_by_number_or_tag(BlockNumberOrTag::Safe)?.unwrap(),
2353            receipts.get(safe_block.number as usize).unwrap().clone()
2354        );
2355        assert_eq!(
2356            provider.receipts_by_number_or_tag(BlockNumberOrTag::Finalized)?.unwrap(),
2357            receipts.get(finalized_block.number as usize).unwrap().clone()
2358        );
2359
2360        Ok(())
2361    }
2362
2363    #[test]
2364    fn test_changeset_reader() -> eyre::Result<()> {
2365        let mut rng = generators::rng();
2366
2367        let (database_blocks, in_memory_blocks) =
2368            random_blocks(&mut rng, TEST_BLOCKS_COUNT, 1, None, None, 0..1);
2369
2370        let first_database_block = database_blocks.first().map(|block| block.number).unwrap();
2371        let last_database_block = database_blocks.last().map(|block| block.number).unwrap();
2372        let first_in_memory_block = in_memory_blocks.first().map(|block| block.number).unwrap();
2373
2374        let accounts = random_eoa_accounts(&mut rng, 2);
2375
2376        let (database_changesets, database_state) = random_changeset_range(
2377            &mut rng,
2378            &database_blocks,
2379            accounts.into_iter().map(|(address, account)| (address, (account, Vec::new()))),
2380            0..0,
2381            0..0,
2382        );
2383        let (in_memory_changesets, in_memory_state) = random_changeset_range(
2384            &mut rng,
2385            &in_memory_blocks,
2386            database_state.iter().map(|(address, (account, storage))| {
2387                (*address, (account.clone(), storage.clone()))
2388            }),
2389            0..0,
2390            0..0,
2391        );
2392
2393        let factory = create_test_provider_factory();
2394
2395        let provider_rw = factory.provider_rw()?;
2396        provider_rw.append_blocks_with_state(
2397            database_blocks
2398                .into_iter()
2399                .map(|b| b.try_recover().expect("failed to seal block with senders"))
2400                .collect(),
2401            &ExecutionOutcome {
2402                bundle: BundleState::new(
2403                    database_state.into_iter().map(|(address, (account, _))| {
2404                        (address, None, Some(account.into()), Default::default())
2405                    }),
2406                    database_changesets.iter().map(|block_changesets| {
2407                        block_changesets.iter().map(|(address, account, _)| {
2408                            (*address, Some(Some(account.clone().into())), [])
2409                        })
2410                    }),
2411                    Vec::new(),
2412                ),
2413                first_block: first_database_block,
2414                ..Default::default()
2415            },
2416            Default::default(),
2417        )?;
2418        provider_rw.commit()?;
2419
2420        let provider = BlockchainProvider::new(factory)?;
2421
2422        let in_memory_changesets = in_memory_changesets.into_iter().next().unwrap();
2423        let chain = NewCanonicalChain::Commit {
2424            new: vec![in_memory_blocks
2425                .first()
2426                .map(|block| {
2427                    let senders = block.senders().expect("failed to recover senders");
2428                    ExecutedBlock {
2429                        recovered_block: Arc::new(RecoveredBlock::new_sealed(
2430                            block.clone(),
2431                            senders,
2432                        )),
2433                        execution_output: Arc::new(BlockExecutionOutput {
2434                            state: BundleState::new(
2435                                in_memory_state.into_iter().map(|(address, (account, _))| {
2436                                    (address, None, Some(account.into()), Default::default())
2437                                }),
2438                                [in_memory_changesets.iter().map(|(address, account, _)| {
2439                                    (*address, Some(Some(account.clone().into())), Vec::new())
2440                                })],
2441                                [],
2442                            ),
2443                            result: BlockExecutionResult {
2444                                receipts: Default::default(),
2445                                requests: Default::default(),
2446                                gas_used: 0,
2447                                blob_gas_used: 0,
2448                            },
2449                        }),
2450                        ..Default::default()
2451                    }
2452                })
2453                .unwrap()],
2454        };
2455        provider.canonical_in_memory_state.update_chain(chain);
2456
2457        assert_eq!(
2458            provider.account_block_changeset(last_database_block).unwrap(),
2459            database_changesets
2460                .into_iter()
2461                .next_back()
2462                .unwrap()
2463                .into_iter()
2464                .sorted_by_key(|(address, _, _)| *address)
2465                .map(|(address, account, _)| AccountBeforeTx { address, info: Some(account) })
2466                .collect::<Vec<_>>()
2467        );
2468        assert_eq!(
2469            provider.account_block_changeset(first_in_memory_block).unwrap(),
2470            in_memory_changesets
2471                .into_iter()
2472                .sorted_by_key(|(address, _, _)| *address)
2473                .map(|(address, account, _)| AccountBeforeTx { address, info: Some(account) })
2474                .collect::<Vec<_>>()
2475        );
2476
2477        Ok(())
2478    }
2479
2480    #[test]
2481    fn test_state_provider_factory() -> eyre::Result<()> {
2482        let mut rng = generators::rng();
2483
2484        // test in-memory state use-cases
2485        let (in_memory_provider, _, in_memory_blocks, _) = provider_with_random_blocks(
2486            &mut rng,
2487            TEST_BLOCKS_COUNT,
2488            TEST_BLOCKS_COUNT,
2489            BlockRangeParams::default(),
2490        )?;
2491
2492        // test database state use-cases
2493        let (only_database_provider, database_blocks, _, _) = provider_with_random_blocks(
2494            &mut rng,
2495            TEST_BLOCKS_COUNT,
2496            0,
2497            BlockRangeParams::default(),
2498        )?;
2499
2500        let blocks = [database_blocks.clone(), in_memory_blocks.clone()].concat();
2501        let first_in_memory_block = in_memory_blocks.first().unwrap();
2502        let first_db_block = database_blocks.first().unwrap();
2503
2504        // test latest state
2505        assert_eq!(
2506            first_in_memory_block.hash(),
2507            in_memory_provider.latest().unwrap().block_hash(first_in_memory_block.number)?.unwrap()
2508        );
2509        // test latest falls back to database state when there's no in-memory block
2510        assert_eq!(
2511            first_db_block.hash(),
2512            only_database_provider.latest().unwrap().block_hash(first_db_block.number)?.unwrap()
2513        );
2514
2515        // test history by block number
2516        assert_eq!(
2517            first_in_memory_block.hash(),
2518            in_memory_provider
2519                .history_by_block_number(first_in_memory_block.number)?
2520                .block_hash(first_in_memory_block.number)?
2521                .unwrap()
2522        );
2523        assert_eq!(
2524            first_db_block.hash(),
2525            only_database_provider
2526                .history_by_block_number(first_db_block.number)?
2527                .block_hash(first_db_block.number)?
2528                .unwrap()
2529        );
2530        assert_eq!(
2531            first_in_memory_block.hash(),
2532            in_memory_provider
2533                .history_by_block_hash(first_in_memory_block.hash())?
2534                .block_hash(first_in_memory_block.number)?
2535                .unwrap()
2536        );
2537        assert!(only_database_provider.history_by_block_hash(B256::random()).is_err());
2538
2539        // test state by block hash
2540        assert_eq!(
2541            first_in_memory_block.hash(),
2542            in_memory_provider
2543                .state_by_block_hash(first_in_memory_block.hash())?
2544                .block_hash(first_in_memory_block.number)?
2545                .unwrap()
2546        );
2547        assert_eq!(
2548            first_db_block.hash(),
2549            only_database_provider
2550                .state_by_block_hash(first_db_block.hash())?
2551                .block_hash(first_db_block.number)?
2552                .unwrap()
2553        );
2554        assert!(only_database_provider.state_by_block_hash(B256::random()).is_err());
2555
2556        // test pending without pending state- falls back to latest
2557        assert_eq!(
2558            first_in_memory_block.hash(),
2559            in_memory_provider
2560                .pending()
2561                .unwrap()
2562                .block_hash(first_in_memory_block.number)
2563                .unwrap()
2564                .unwrap()
2565        );
2566
2567        // adding a pending block to state can test pending() and  pending_state_by_hash() function
2568        let pending_block = database_blocks[database_blocks.len() - 1].clone();
2569        only_database_provider.canonical_in_memory_state.set_pending_block(ExecutedBlock {
2570            recovered_block: Arc::new(RecoveredBlock::new_sealed(
2571                pending_block.clone(),
2572                Default::default(),
2573            )),
2574            ..Default::default()
2575        });
2576
2577        assert_eq!(
2578            pending_block.hash(),
2579            only_database_provider
2580                .pending()
2581                .unwrap()
2582                .block_hash(pending_block.number)
2583                .unwrap()
2584                .unwrap()
2585        );
2586
2587        assert_eq!(
2588            pending_block.hash(),
2589            only_database_provider
2590                .pending_state_by_hash(pending_block.hash())?
2591                .unwrap()
2592                .block_hash(pending_block.number)?
2593                .unwrap()
2594        );
2595
2596        // test state by block number or tag
2597        assert_eq!(
2598            first_in_memory_block.hash(),
2599            in_memory_provider
2600                .state_by_block_number_or_tag(BlockNumberOrTag::Number(
2601                    first_in_memory_block.number
2602                ))?
2603                .block_hash(first_in_memory_block.number)?
2604                .unwrap()
2605        );
2606        assert_eq!(
2607            first_in_memory_block.hash(),
2608            in_memory_provider
2609                .state_by_block_number_or_tag(BlockNumberOrTag::Latest)?
2610                .block_hash(first_in_memory_block.number)?
2611                .unwrap()
2612        );
2613        // test state by block tag for safe block
2614        let safe_block = in_memory_blocks[in_memory_blocks.len() - 2].clone();
2615        in_memory_provider.canonical_in_memory_state.set_safe(safe_block.clone_sealed_header());
2616        assert_eq!(
2617            safe_block.hash(),
2618            in_memory_provider
2619                .state_by_block_number_or_tag(BlockNumberOrTag::Safe)?
2620                .block_hash(safe_block.number)?
2621                .unwrap()
2622        );
2623        // test state by block tag for finalized block
2624        let finalized_block = in_memory_blocks[in_memory_blocks.len() - 3].clone();
2625        in_memory_provider
2626            .canonical_in_memory_state
2627            .set_finalized(finalized_block.clone_sealed_header());
2628        assert_eq!(
2629            finalized_block.hash(),
2630            in_memory_provider
2631                .state_by_block_number_or_tag(BlockNumberOrTag::Finalized)?
2632                .block_hash(finalized_block.number)?
2633                .unwrap()
2634        );
2635        // test state by block tag for earliest block
2636        let earliest_block = blocks.first().unwrap().clone();
2637        assert_eq!(
2638            earliest_block.hash(),
2639            only_database_provider
2640                .state_by_block_number_or_tag(BlockNumberOrTag::Earliest)?
2641                .block_hash(earliest_block.number)?
2642                .unwrap()
2643        );
2644
2645        Ok(())
2646    }
2647
2648    #[test]
2649    fn test_block_id_reader() -> eyre::Result<()> {
2650        // Create a new provider
2651        let mut rng = generators::rng();
2652        let (provider, _, in_memory_blocks, _) = provider_with_random_blocks(
2653            &mut rng,
2654            TEST_BLOCKS_COUNT,
2655            TEST_BLOCKS_COUNT,
2656            BlockRangeParams::default(),
2657        )?;
2658
2659        // Set the pending block in memory
2660        let pending_block = in_memory_blocks.last().unwrap();
2661        provider.canonical_in_memory_state.set_pending_block(ExecutedBlock {
2662            recovered_block: Arc::new(RecoveredBlock::new_sealed(
2663                pending_block.clone(),
2664                Default::default(),
2665            )),
2666            ..Default::default()
2667        });
2668
2669        // Set the safe block in memory
2670        let safe_block = in_memory_blocks[in_memory_blocks.len() - 2].clone();
2671        provider.canonical_in_memory_state.set_safe(safe_block.clone_sealed_header());
2672
2673        // Set the finalized block in memory
2674        let finalized_block = in_memory_blocks[in_memory_blocks.len() - 3].clone();
2675        provider.canonical_in_memory_state.set_finalized(finalized_block.clone_sealed_header());
2676
2677        // Verify the pending block number and hash
2678        assert_eq!(
2679            provider.pending_block_num_hash()?,
2680            Some(BlockNumHash { number: pending_block.number, hash: pending_block.hash() })
2681        );
2682
2683        // Verify the safe block number and hash
2684        assert_eq!(
2685            provider.safe_block_num_hash()?,
2686            Some(BlockNumHash { number: safe_block.number, hash: safe_block.hash() })
2687        );
2688
2689        // Verify the finalized block number and hash
2690        assert_eq!(
2691            provider.finalized_block_num_hash()?,
2692            Some(BlockNumHash { number: finalized_block.number, hash: finalized_block.hash() })
2693        );
2694
2695        Ok(())
2696    }
2697
2698    macro_rules! test_by_tx_range {
2699        ([$(($method:ident, $data_extractor:expr)),* $(,)?]) => {{
2700
2701            // Get the number methods being tested.
2702            // Since each method tested will move a block from memory to storage, this ensures we have enough.
2703            let extra_blocks = [$(stringify!($method)),*].len();
2704
2705            let mut rng = generators::rng();
2706            let (provider, mut database_blocks, mut in_memory_blocks, receipts) = provider_with_random_blocks(
2707                &mut rng,
2708                TEST_BLOCKS_COUNT,
2709                TEST_BLOCKS_COUNT + extra_blocks,
2710                BlockRangeParams {
2711                    tx_count: TEST_TRANSACTIONS_COUNT..TEST_TRANSACTIONS_COUNT,
2712                    ..Default::default()
2713                },
2714            )?;
2715
2716            $(
2717                // Since data moves for each tried method, need to recalculate everything
2718                let db_tx_count =
2719                    database_blocks.iter().map(|b| b.transaction_count()).sum::<usize>() as u64;
2720                let in_mem_tx_count =
2721                    in_memory_blocks.iter().map(|b| b.transaction_count()).sum::<usize>() as u64;
2722
2723                let db_range = 0..=(db_tx_count - 1);
2724                let in_mem_range = db_tx_count..=(in_mem_tx_count + db_range.end());
2725
2726                // Retrieve the expected database data
2727                let database_data =
2728                    database_blocks.iter().flat_map(|b| $data_extractor(b, &receipts)).collect::<Vec<_>>();
2729                assert_eq!(provider.$method(db_range.clone())?, database_data, "full db data");
2730
2731                // Retrieve the expected in-memory data
2732                let in_memory_data =
2733                    in_memory_blocks.iter().flat_map(|b| $data_extractor(b, &receipts)).collect::<Vec<_>>();
2734                assert_eq!(provider.$method(in_mem_range.clone())?, in_memory_data, "full mem data");
2735
2736                // Test partial in-memory range
2737                assert_eq!(
2738                    &provider.$method(in_mem_range.start() + 1..=in_mem_range.end() - 1)?,
2739                    &in_memory_data[1..in_memory_data.len() - 1],
2740                    "partial mem data"
2741                );
2742
2743                // Test range in memory to unbounded end
2744                assert_eq!(provider.$method(in_mem_range.start() + 1..)?, &in_memory_data[1..], "unbounded mem data");
2745
2746                // Test last element in-memory
2747                assert_eq!(provider.$method(in_mem_range.end()..)?, &in_memory_data[in_memory_data.len() -1 ..], "last mem data");
2748
2749                // Test range that spans database and in-memory with unbounded end
2750                assert_eq!(
2751                    provider.$method(in_mem_range.start() - 2..)?,
2752                    database_data[database_data.len() - 2..]
2753                        .iter()
2754                        .chain(&in_memory_data[..])
2755                        .cloned()
2756                        .collect::<Vec<_>>(),
2757                    "unbounded span data"
2758                );
2759
2760                // Test range that spans database and in-memory
2761                {
2762                    // This block will be persisted to disk and removed from memory AFTER the first database query. This ensures that we query the in-memory state before the database avoiding any race condition.
2763                    persist_block_after_db_tx_creation(provider.clone(), in_memory_blocks[0].number);
2764
2765                    assert_eq!(
2766                        provider.$method(in_mem_range.start() - 2..=in_mem_range.end() - 1)?,
2767                        database_data[database_data.len() - 2..]
2768                            .iter()
2769                            .chain(&in_memory_data[..in_memory_data.len() - 1])
2770                            .cloned()
2771                            .collect::<Vec<_>>(),
2772                        "span data"
2773                    );
2774
2775                    // Adjust our blocks accordingly
2776                    database_blocks.push(in_memory_blocks.remove(0));
2777                }
2778
2779                // Test invalid range
2780                let start_tx_num = u64::MAX;
2781                let end_tx_num = u64::MAX;
2782                let result = provider.$method(start_tx_num..end_tx_num)?;
2783                assert!(result.is_empty(), "No data should be found for an invalid transaction range");
2784
2785                // Test empty range
2786                let result = provider.$method(in_mem_range.end()+10..in_mem_range.end()+20)?;
2787                assert!(result.is_empty(), "No data should be found for an empty transaction range");
2788            )*
2789        }};
2790    }
2791
2792    #[test]
2793    fn test_methods_by_tx_range() -> eyre::Result<()> {
2794        test_by_tx_range!([
2795            (senders_by_tx_range, |block: &SealedBlock<Block>, _: &Vec<Vec<Receipt>>| block
2796                .senders()
2797                .unwrap()),
2798            (transactions_by_tx_range, |block: &SealedBlock<Block>, _: &Vec<Vec<Receipt>>| block
2799                .body()
2800                .transactions
2801                .clone()),
2802            (receipts_by_tx_range, |block: &SealedBlock<Block>, receipts: &Vec<Vec<Receipt>>| {
2803                receipts[block.number as usize].clone()
2804            })
2805        ]);
2806
2807        Ok(())
2808    }
2809
2810    macro_rules! test_by_block_range {
2811        ([$(($method:ident, $data_extractor:expr)),* $(,)?]) => {{
2812            // Get the number methods being tested.
2813            // Since each method tested will move a block from memory to storage, this ensures we have enough.
2814            let extra_blocks = [$(stringify!($method)),*].len();
2815
2816            let mut rng = generators::rng();
2817            let (provider, mut database_blocks, mut in_memory_blocks, _) = provider_with_random_blocks(
2818                &mut rng,
2819                TEST_BLOCKS_COUNT,
2820                TEST_BLOCKS_COUNT + extra_blocks,
2821                BlockRangeParams {
2822                    tx_count: TEST_TRANSACTIONS_COUNT..TEST_TRANSACTIONS_COUNT,
2823                    ..Default::default()
2824                },
2825            )?;
2826
2827            $(
2828                // Since data moves for each tried method, need to recalculate everything
2829                let db_block_count = database_blocks.len() as u64;
2830                let in_mem_block_count = in_memory_blocks.len() as u64;
2831
2832                let db_range = 0..=db_block_count - 1;
2833                let in_mem_range = db_block_count..=(in_mem_block_count + db_range.end());
2834
2835                // Retrieve the expected database data
2836                let database_data =
2837                    database_blocks.iter().map(|b| $data_extractor(b)).collect::<Vec<_>>();
2838                assert_eq!(provider.$method(db_range.clone())?, database_data);
2839
2840                // Retrieve the expected in-memory data
2841                let in_memory_data =
2842                    in_memory_blocks.iter().map(|b| $data_extractor(b)).collect::<Vec<_>>();
2843                assert_eq!(provider.$method(in_mem_range.clone())?, in_memory_data);
2844
2845                // Test partial in-memory range
2846                assert_eq!(
2847                    &provider.$method(in_mem_range.start() + 1..=in_mem_range.end() - 1)?,
2848                    &in_memory_data[1..in_memory_data.len() - 1]
2849                );
2850
2851                // Test range that spans database and in-memory
2852                {
2853
2854                    // This block will be persisted to disk and removed from memory AFTER the first database query. This ensures that we query the in-memory state before the database avoiding any race condition.
2855                    persist_block_after_db_tx_creation(provider.clone(), in_memory_blocks[0].number);
2856
2857                    assert_eq!(
2858                        provider.$method(in_mem_range.start() - 2..=in_mem_range.end() - 1)?,
2859                        database_data[database_data.len() - 2..]
2860                            .iter()
2861                            .chain(&in_memory_data[..in_memory_data.len() - 1])
2862                            .cloned()
2863                            .collect::<Vec<_>>()
2864                    );
2865
2866                    // Adjust our blocks accordingly
2867                    database_blocks.push(in_memory_blocks.remove(0));
2868                }
2869
2870                // Test invalid range
2871                let start_block_num = u64::MAX;
2872                let end_block_num = u64::MAX;
2873                let result = provider.$method(start_block_num..=end_block_num-1)?;
2874                assert!(result.is_empty(), "No data should be found for an invalid block range");
2875
2876                // Test valid range with empty results
2877                let result = provider.$method(in_mem_range.end() + 10..=in_mem_range.end() + 20)?;
2878                assert!(result.is_empty(), "No data should be found for an empty block range");
2879            )*
2880        }};
2881    }
2882
2883    #[test]
2884    fn test_methods_by_block_range() -> eyre::Result<()> {
2885        // todo(joshie) add canonical_hashes_range below after changing its interface into range
2886        // instead start end
2887        test_by_block_range!([
2888            (headers_range, |block: &SealedBlock<Block>| block.header().clone()),
2889            (sealed_headers_range, |block: &SealedBlock<Block>| block.clone_sealed_header()),
2890            (block_range, |block: &SealedBlock<Block>| block.clone().into_block()),
2891            (block_with_senders_range, |block: &SealedBlock<Block>| block
2892                .clone()
2893                .try_recover()
2894                .unwrap()),
2895            (recovered_block_range, |block: &SealedBlock<Block>| block
2896                .clone()
2897                .try_recover()
2898                .unwrap()),
2899            (transactions_by_block_range, |block: &SealedBlock<Block>| block
2900                .body()
2901                .transactions
2902                .clone()),
2903        ]);
2904
2905        Ok(())
2906    }
2907
2908    /// Helper macro to call a provider method based on argument count and check its result
2909    macro_rules! call_method {
2910        ($provider:expr, $method:ident, ($($args:expr),*), $expected_item:expr) => {{
2911            let result = $provider.$method($($args),*)?;
2912            assert_eq!(
2913                result,
2914                $expected_item,
2915                "{}: item does not match the expected item for arguments {:?}",
2916                stringify!($method),
2917                ($($args),*)
2918            );
2919        }};
2920
2921        // Handle valid or invalid arguments for one argument
2922        (ONE, $provider:expr, $method:ident, $item_extractor:expr, $txnum:expr, $txhash:expr, $block:expr, $receipts:expr) => {{
2923            let (arg, expected_item) = $item_extractor($block, $txnum($block), $txhash($block), $receipts);
2924            call_method!($provider, $method, (arg), expected_item);
2925        }};
2926
2927        // Handle valid or invalid arguments for two arguments
2928        (TWO, $provider:expr, $method:ident, $item_extractor:expr, $txnum:expr, $txhash:expr, $block:expr, $receipts:expr) => {{
2929            let ((arg1, arg2), expected_item) = $item_extractor($block, $txnum($block), $txhash($block), $receipts);
2930            call_method!($provider, $method, (arg1, arg2), expected_item);
2931        }};
2932    }
2933
2934    /// Macro to test non-range methods.
2935    ///
2936    /// ( `NUMBER_ARGUMENTS`, METHOD, FN -> ((`METHOD_ARGUMENT(s)`,...), `EXPECTED_RESULT`),
2937    /// `INVALID_ARGUMENTS`)
2938    macro_rules! test_non_range {
2939    ([$(($arg_count:ident, $method:ident, $item_extractor:expr, $invalid_args:expr)),* $(,)?]) => {{
2940
2941        // Get the number methods being tested.
2942        // Since each method tested will move a block from memory to storage, this ensures we have enough.
2943        let extra_blocks = [$(stringify!($arg_count)),*].len();
2944
2945        let mut rng = generators::rng();
2946        let (provider, mut database_blocks, in_memory_blocks, receipts) = provider_with_random_blocks(
2947            &mut rng,
2948            TEST_BLOCKS_COUNT,
2949            TEST_BLOCKS_COUNT + extra_blocks,
2950            BlockRangeParams {
2951                tx_count: TEST_TRANSACTIONS_COUNT..TEST_TRANSACTIONS_COUNT,
2952                ..Default::default()
2953            },
2954        )?;
2955
2956        let mut in_memory_blocks: std::collections::VecDeque<_> = in_memory_blocks.into();
2957
2958        $(
2959            let tx_hash = |block: &SealedBlock<Block>| *block.body().transactions[0].tx_hash();
2960            let tx_num = |block: &SealedBlock<Block>| {
2961                database_blocks
2962                    .iter()
2963                    .chain(in_memory_blocks.iter())
2964                    .take_while(|b| b.number < block.number)
2965                    .map(|b| b.transaction_count())
2966                    .sum::<usize>() as u64
2967            };
2968
2969            // Ensure that the first generated in-memory block exists
2970            {
2971                // This block will be persisted to disk and removed from memory AFTER the first database query. This ensures that we query the in-memory state before the database avoiding any race condition.
2972                persist_block_after_db_tx_creation(provider.clone(), in_memory_blocks[0].number);
2973
2974                call_method!($arg_count, provider, $method, $item_extractor, tx_num, tx_hash, &in_memory_blocks[0], &receipts);
2975
2976                // Move the block as well in our own structures
2977                database_blocks.push(in_memory_blocks.pop_front().unwrap());
2978            }
2979
2980            // database_blocks is changed above
2981            let tx_num = |block: &SealedBlock<Block>| {
2982                database_blocks
2983                    .iter()
2984                    .chain(in_memory_blocks.iter())
2985                    .take_while(|b| b.number < block.number)
2986                    .map(|b| b.transaction_count())
2987                    .sum::<usize>() as u64
2988            };
2989
2990            // Invalid/Non-existent argument should return `None`
2991            {
2992                call_method!($arg_count, provider, $method, |_,_,_,_|  ($invalid_args, None), tx_num, tx_hash, &in_memory_blocks[0], &receipts);
2993            }
2994
2995            // Check that the item is only in memory and not in database
2996            {
2997                let last_mem_block = &in_memory_blocks[in_memory_blocks.len() - 1];
2998
2999                let (args, expected_item) = $item_extractor(last_mem_block, tx_num(last_mem_block), tx_hash(last_mem_block), &receipts);
3000                call_method!($arg_count, provider, $method, |_,_,_,_| (args.clone(), expected_item), tx_num, tx_hash, last_mem_block, &receipts);
3001
3002                // Ensure the item is not in storage
3003                call_method!($arg_count, provider.database, $method, |_,_,_,_|  (args, None), tx_num, tx_hash, last_mem_block, &receipts);
3004            }
3005        )*
3006    }};
3007}
3008
3009    #[test]
3010    fn test_non_range_methods() -> eyre::Result<()> {
3011        let test_tx_index = 0;
3012
3013        test_non_range!([
3014            (
3015                ONE,
3016                header,
3017                |block: &SealedBlock<Block>, _: TxNumber, _: B256, _: &Vec<Vec<Receipt>>| (
3018                    block.hash(),
3019                    Some(block.header().clone())
3020                ),
3021                B256::random()
3022            ),
3023            (
3024                ONE,
3025                header_by_number,
3026                |block: &SealedBlock<Block>, _: TxNumber, _: B256, _: &Vec<Vec<Receipt>>| (
3027                    block.number,
3028                    Some(block.header().clone())
3029                ),
3030                u64::MAX
3031            ),
3032            (
3033                ONE,
3034                sealed_header,
3035                |block: &SealedBlock<Block>, _: TxNumber, _: B256, _: &Vec<Vec<Receipt>>| (
3036                    block.number,
3037                    Some(block.clone_sealed_header())
3038                ),
3039                u64::MAX
3040            ),
3041            (
3042                ONE,
3043                block_hash,
3044                |block: &SealedBlock<Block>, _: TxNumber, _: B256, _: &Vec<Vec<Receipt>>| (
3045                    block.number,
3046                    Some(block.hash())
3047                ),
3048                u64::MAX
3049            ),
3050            (
3051                ONE,
3052                block_number,
3053                |block: &SealedBlock<Block>, _: TxNumber, _: B256, _: &Vec<Vec<Receipt>>| (
3054                    block.hash(),
3055                    Some(block.number)
3056                ),
3057                B256::random()
3058            ),
3059            (
3060                ONE,
3061                block,
3062                |block: &SealedBlock<Block>, _: TxNumber, _: B256, _: &Vec<Vec<Receipt>>| (
3063                    BlockHashOrNumber::Hash(block.hash()),
3064                    Some(block.clone().into_block())
3065                ),
3066                BlockHashOrNumber::Hash(B256::random())
3067            ),
3068            (
3069                ONE,
3070                block,
3071                |block: &SealedBlock<Block>, _: TxNumber, _: B256, _: &Vec<Vec<Receipt>>| (
3072                    BlockHashOrNumber::Number(block.number),
3073                    Some(block.clone().into_block())
3074                ),
3075                BlockHashOrNumber::Number(u64::MAX)
3076            ),
3077            (
3078                ONE,
3079                block_body_indices,
3080                |block: &SealedBlock<Block>, tx_num: TxNumber, _: B256, _: &Vec<Vec<Receipt>>| (
3081                    block.number,
3082                    Some(StoredBlockBodyIndices {
3083                        first_tx_num: tx_num,
3084                        tx_count: block.transaction_count() as u64
3085                    })
3086                ),
3087                u64::MAX
3088            ),
3089            (
3090                TWO,
3091                recovered_block,
3092                |block: &SealedBlock<Block>, _: TxNumber, _: B256, _: &Vec<Vec<Receipt>>| (
3093                    (BlockHashOrNumber::Number(block.number), TransactionVariant::WithHash),
3094                    block.clone().try_recover().ok()
3095                ),
3096                (BlockHashOrNumber::Number(u64::MAX), TransactionVariant::WithHash)
3097            ),
3098            (
3099                TWO,
3100                recovered_block,
3101                |block: &SealedBlock<Block>, _: TxNumber, _: B256, _: &Vec<Vec<Receipt>>| (
3102                    (BlockHashOrNumber::Hash(block.hash()), TransactionVariant::WithHash),
3103                    block.clone().try_recover().ok()
3104                ),
3105                (BlockHashOrNumber::Hash(B256::random()), TransactionVariant::WithHash)
3106            ),
3107            (
3108                TWO,
3109                sealed_block_with_senders,
3110                |block: &SealedBlock<Block>, _: TxNumber, _: B256, _: &Vec<Vec<Receipt>>| (
3111                    (BlockHashOrNumber::Number(block.number), TransactionVariant::WithHash),
3112                    block.clone().try_recover().ok()
3113                ),
3114                (BlockHashOrNumber::Number(u64::MAX), TransactionVariant::WithHash)
3115            ),
3116            (
3117                TWO,
3118                sealed_block_with_senders,
3119                |block: &SealedBlock<Block>, _: TxNumber, _: B256, _: &Vec<Vec<Receipt>>| (
3120                    (BlockHashOrNumber::Hash(block.hash()), TransactionVariant::WithHash),
3121                    block.clone().try_recover().ok()
3122                ),
3123                (BlockHashOrNumber::Hash(B256::random()), TransactionVariant::WithHash)
3124            ),
3125            (
3126                ONE,
3127                transaction_id,
3128                |_: &SealedBlock<Block>, tx_num: TxNumber, tx_hash: B256, _: &Vec<Vec<Receipt>>| (
3129                    tx_hash,
3130                    Some(tx_num)
3131                ),
3132                B256::random()
3133            ),
3134            (
3135                ONE,
3136                transaction_by_id,
3137                |block: &SealedBlock<Block>, tx_num: TxNumber, _: B256, _: &Vec<Vec<Receipt>>| (
3138                    tx_num,
3139                    Some(block.body().transactions[test_tx_index].clone())
3140                ),
3141                u64::MAX
3142            ),
3143            (
3144                ONE,
3145                transaction_by_id_unhashed,
3146                |block: &SealedBlock<Block>, tx_num: TxNumber, _: B256, _: &Vec<Vec<Receipt>>| (
3147                    tx_num,
3148                    Some(block.body().transactions[test_tx_index].clone())
3149                ),
3150                u64::MAX
3151            ),
3152            (
3153                ONE,
3154                transaction_by_hash,
3155                |block: &SealedBlock<Block>, _: TxNumber, tx_hash: B256, _: &Vec<Vec<Receipt>>| (
3156                    tx_hash,
3157                    Some(block.body().transactions[test_tx_index].clone())
3158                ),
3159                B256::random()
3160            ),
3161            (
3162                ONE,
3163                transaction_by_hash_with_meta_and_sender,
3164                |block: &SealedBlock<Block>, _: TxNumber, tx_hash: B256, _: &Vec<Vec<Receipt>>| {
3165                    let tx = block.body().transactions[test_tx_index].clone();
3166                    let sender = tx.recover_signer().ok();
3167                    let meta = TransactionMeta {
3168                        tx_hash,
3169                        index: test_tx_index as u64,
3170                        block_hash: block.hash(),
3171                        block_number: block.number,
3172                        base_fee: block.base_fee_per_gas,
3173                        excess_blob_gas: block.excess_blob_gas,
3174                        timestamp: block.timestamp,
3175                    };
3176                    (tx_hash, Some((tx, meta, sender)))
3177                },
3178                B256::random()
3179            ),
3180            (
3181                ONE,
3182                block_by_transaction_id,
3183                |block: &SealedBlock<Block>, tx_num: TxNumber, _: B256, _: &Vec<Vec<Receipt>>| (
3184                    tx_num,
3185                    Some(block.number)
3186                ),
3187                u64::MAX
3188            ),
3189            (
3190                ONE,
3191                transactions_by_block,
3192                |block: &SealedBlock<Block>, _: TxNumber, _: B256, _: &Vec<Vec<Receipt>>| (
3193                    BlockHashOrNumber::Number(block.number),
3194                    Some(block.body().transactions.clone())
3195                ),
3196                BlockHashOrNumber::Number(u64::MAX)
3197            ),
3198            (
3199                ONE,
3200                transactions_by_block,
3201                |block: &SealedBlock<Block>, _: TxNumber, _: B256, _: &Vec<Vec<Receipt>>| (
3202                    BlockHashOrNumber::Hash(block.hash()),
3203                    Some(block.body().transactions.clone())
3204                ),
3205                BlockHashOrNumber::Number(u64::MAX)
3206            ),
3207            (
3208                ONE,
3209                transaction_sender,
3210                |block: &SealedBlock<Block>, tx_num: TxNumber, _: B256, _: &Vec<Vec<Receipt>>| (
3211                    tx_num,
3212                    block.body().transactions[test_tx_index].recover_signer().ok()
3213                ),
3214                u64::MAX
3215            ),
3216            (
3217                ONE,
3218                receipt,
3219                |block: &SealedBlock<Block>,
3220                 tx_num: TxNumber,
3221                 _: B256,
3222                 receipts: &Vec<Vec<Receipt>>| (
3223                    tx_num,
3224                    Some(receipts[block.number as usize][test_tx_index].clone())
3225                ),
3226                u64::MAX
3227            ),
3228            (
3229                ONE,
3230                receipt_by_hash,
3231                |block: &SealedBlock<Block>,
3232                 _: TxNumber,
3233                 tx_hash: B256,
3234                 receipts: &Vec<Vec<Receipt>>| (
3235                    tx_hash,
3236                    Some(receipts[block.number as usize][test_tx_index].clone())
3237                ),
3238                B256::random()
3239            ),
3240            (
3241                ONE,
3242                receipts_by_block,
3243                |block: &SealedBlock<Block>, _: TxNumber, _: B256, receipts: &Vec<Vec<Receipt>>| (
3244                    BlockHashOrNumber::Number(block.number),
3245                    Some(receipts[block.number as usize].clone())
3246                ),
3247                BlockHashOrNumber::Number(u64::MAX)
3248            ),
3249            (
3250                ONE,
3251                receipts_by_block,
3252                |block: &SealedBlock<Block>, _: TxNumber, _: B256, receipts: &Vec<Vec<Receipt>>| (
3253                    BlockHashOrNumber::Hash(block.hash()),
3254                    Some(receipts[block.number as usize].clone())
3255                ),
3256                BlockHashOrNumber::Hash(B256::random())
3257            ),
3258            // TODO: withdrawals, requests, ommers
3259        ]);
3260
3261        Ok(())
3262    }
3263
3264    #[test]
3265    fn test_race() -> eyre::Result<()> {
3266        let mut rng = generators::rng();
3267        let (provider, _, in_memory_blocks, _) = provider_with_random_blocks(
3268            &mut rng,
3269            TEST_BLOCKS_COUNT - 1,
3270            TEST_BLOCKS_COUNT + 1,
3271            BlockRangeParams {
3272                tx_count: TEST_TRANSACTIONS_COUNT..TEST_TRANSACTIONS_COUNT,
3273                ..Default::default()
3274            },
3275        )?;
3276
3277        // Old implementation was querying the database first. This is problematic, if there are
3278        // changes AFTER the database transaction is created.
3279        let old_transaction_hash_fn =
3280            |hash: B256,
3281             canonical_in_memory_state: CanonicalInMemoryState,
3282             factory: ProviderFactory<MockNodeTypesWithDB>| {
3283                assert!(factory.transaction_by_hash(hash)?.is_none(), "should not be in database");
3284                Ok::<_, ProviderError>(canonical_in_memory_state.transaction_by_hash(hash))
3285            };
3286
3287        // Correct implementation queries in-memory first
3288        let correct_transaction_hash_fn =
3289            |hash: B256,
3290             canonical_in_memory_state: CanonicalInMemoryState,
3291             _factory: ProviderFactory<MockNodeTypesWithDB>| {
3292                if let Some(tx) = canonical_in_memory_state.transaction_by_hash(hash) {
3293                    return Ok::<_, ProviderError>(Some(tx));
3294                }
3295                panic!("should not be in database");
3296                // _factory.transaction_by_hash(hash)
3297            };
3298
3299        // OLD BEHAVIOUR
3300        {
3301            // This will persist block 1 AFTER a database is created. Moving it from memory to
3302            // storage.
3303            persist_block_after_db_tx_creation(provider.clone(), in_memory_blocks[0].number);
3304            let to_be_persisted_tx = in_memory_blocks[0].body().transactions[0].clone();
3305
3306            // Even though the block exists, given the order of provider queries done in the method
3307            // above, we do not see it.
3308            assert!(matches!(
3309                old_transaction_hash_fn(
3310                    *to_be_persisted_tx.tx_hash(),
3311                    provider.canonical_in_memory_state(),
3312                    provider.database.clone()
3313                ),
3314                Ok(None)
3315            ));
3316        }
3317
3318        // CORRECT BEHAVIOUR
3319        {
3320            // This will persist block 1 AFTER a database is created. Moving it from memory to
3321            // storage.
3322            persist_block_after_db_tx_creation(provider.clone(), in_memory_blocks[1].number);
3323            let to_be_persisted_tx = in_memory_blocks[1].body().transactions[0].clone();
3324
3325            assert_eq!(
3326                correct_transaction_hash_fn(
3327                    *to_be_persisted_tx.tx_hash(),
3328                    provider.canonical_in_memory_state(),
3329                    provider.database
3330                )
3331                .unwrap(),
3332                Some(to_be_persisted_tx)
3333            );
3334        }
3335
3336        Ok(())
3337    }
3338
3339    fn random_account(nonce: u64) -> (Address, Account) {
3340        (Address::random(), Account { nonce, balance: U256::from(nonce), ..Default::default() })
3341    }
3342
3343    /// [`BlockchainProvider::new`] needs a genesis header to initialize its chain tracker.
3344    fn test_provider_factory_with_genesis() -> eyre::Result<ProviderFactory<MockNodeTypesWithDB>> {
3345        let factory = create_test_provider_factory();
3346        let provider_rw = factory.provider_rw()?;
3347        let mut rng = generators::rng();
3348        let genesis =
3349            random_block(&mut rng, 0, BlockParams { tx_count: Some(0), ..Default::default() });
3350        provider_rw
3351            .insert_block(&genesis.try_recover().expect("failed to seal block with senders"))?;
3352        provider_rw.save_stage_checkpoint(StageId::Finish, StageCheckpoint::new(0))?;
3353        provider_rw.commit()?;
3354        Ok(factory)
3355    }
3356
3357    #[test]
3358    fn state_range_provider_account_range_is_sorted_and_bounded() -> eyre::Result<()> {
3359        let factory = test_provider_factory_with_genesis()?;
3360        let provider_rw = factory.provider_rw()?;
3361
3362        let accounts: Vec<_> = (0..5u64).map(random_account).collect();
3363        provider_rw.insert_account_for_hashing(
3364            accounts.iter().map(|(address, account)| (*address, Some(account.clone()))),
3365        )?;
3366        provider_rw.commit()?;
3367
3368        let provider = BlockchainProvider::new(factory)?;
3369
3370        let mut expected: Vec<_> = accounts
3371            .iter()
3372            .map(|(address, account)| (keccak256(address), account.clone()))
3373            .collect();
3374        expected.sort_by_key(|(hash, _)| *hash);
3375        let state = provider.state_range_provider(EMPTY_ROOT_HASH)?.unwrap();
3376
3377        let all = state.account_range(B256::ZERO, B256::repeat_byte(0xff), 10_000)?;
3378        assert_eq!(all.end, RangeEnd::Exhausted);
3379        assert_eq!(all.items, expected);
3380
3381        // The limit exactly matches the second account's hash, so the range ends there rather
3382        // than by exhausting the trie.
3383        let bounded = state.account_range(B256::ZERO, expected[1].0, 10_000)?;
3384        assert_eq!(bounded.end, RangeEnd::HashLimit);
3385        assert_eq!(bounded.items, expected[..2]);
3386
3387        Ok(())
3388    }
3389
3390    #[test]
3391    fn state_range_view_checks_snap_attempt_on_its_snapshot() -> eyre::Result<()> {
3392        let factory = test_provider_factory_with_genesis()?;
3393        let provider = BlockchainProvider::new(factory.clone())?;
3394        let (address, account) = random_account(1);
3395        let mut attempt = SnapAttempt::start(None, BlockNumHash::default(), B256::ZERO);
3396
3397        // A snapshot taken before the attempt starts keeps serving, without its downloads.
3398        let before_attempt = factory.provider()?;
3399        let provider_rw = factory.provider_rw()?;
3400        provider_rw.write_snap_attempt(&attempt)?;
3401        provider_rw.insert_account_for_hashing([(address, Some(account))])?;
3402        provider_rw.commit()?;
3403        let state = provider
3404            .state_range_view(before_attempt, None, EMPTY_ROOT_HASH)?
3405            .expect("snapshot holds no attempt");
3406        assert_eq!(state.account_range(B256::ZERO, B256::repeat_byte(0xff), 10_000)?.items, []);
3407
3408        // A snapshot taken while the attempt is unverified stays refused after verification.
3409        let unverified = factory.provider()?;
3410        attempt.verify();
3411        let provider_rw = factory.provider_rw()?;
3412        provider_rw.write_snap_attempt(&attempt)?;
3413        provider_rw.insert_account_for_hashing([(address, None)])?;
3414        provider_rw.commit()?;
3415        assert!(provider.state_range_view(unverified, None, EMPTY_ROOT_HASH)?.is_none());
3416
3417        Ok(())
3418    }
3419
3420    #[test]
3421    fn state_range_provider_account_range_respects_response_bytes() -> eyre::Result<()> {
3422        let factory = test_provider_factory_with_genesis()?;
3423        let provider_rw = factory.provider_rw()?;
3424
3425        let accounts: Vec<_> = (0..5u64).map(random_account).collect();
3426        provider_rw.insert_account_for_hashing(
3427            accounts.iter().map(|(address, account)| (*address, Some(account.clone()))),
3428        )?;
3429        provider_rw.commit()?;
3430
3431        let provider = BlockchainProvider::new(factory)?;
3432        let state = provider.state_range_provider(EMPTY_ROOT_HASH)?.unwrap();
3433
3434        // Budget only fits a single account.
3435        let partial = state.account_range(B256::ZERO, B256::repeat_byte(0xff), 150)?;
3436        assert_eq!(partial.end, RangeEnd::ByteLimit);
3437        assert_eq!(partial.items.len(), 1);
3438
3439        Ok(())
3440    }
3441
3442    #[test]
3443    fn state_range_provider_storage_range_and_root() -> eyre::Result<()> {
3444        let factory = test_provider_factory_with_genesis()?;
3445        let provider_rw = factory.provider_rw()?;
3446
3447        let (address, account) = random_account(1);
3448        let hashed_address = keccak256(address);
3449        provider_rw.insert_account_for_hashing([(address, Some(account))])?;
3450        let slots = [
3451            StorageEntry { key: B256::with_last_byte(1), value: U256::from(10) },
3452            StorageEntry { key: B256::with_last_byte(2), value: U256::from(20) },
3453        ];
3454        provider_rw.insert_storage_for_hashing([(address, slots)])?;
3455        provider_rw.commit()?;
3456
3457        let provider = BlockchainProvider::new(factory)?;
3458        let state = provider.state_range_provider(EMPTY_ROOT_HASH)?.unwrap();
3459
3460        let expected_root = provider.latest()?.storage_root(address, HashedStorage::default())?;
3461        assert_eq!(state.storage_root_by_hash(hashed_address)?, expected_root);
3462
3463        let returned = state
3464            .storage_range(hashed_address, B256::ZERO, B256::repeat_byte(0xff), 10_000)?
3465            .unwrap();
3466        assert_eq!(returned.end, RangeEnd::Exhausted);
3467        let mut expected: Vec<_> =
3468            slots.iter().map(|entry| (keccak256(entry.key), entry.value)).collect();
3469        expected.sort_by_key(|(hash, _)| *hash);
3470        assert_eq!(returned.items, expected);
3471
3472        // `start == limit == ZERO` means the first real slot's hash already reaches the limit.
3473        let empty_window =
3474            state.storage_range(hashed_address, B256::ZERO, B256::ZERO, 10_000)?.unwrap();
3475        assert_eq!(empty_window.end, RangeEnd::HashLimit);
3476        assert_eq!(empty_window.items, expected[..1]);
3477
3478        // An account absent from the trie is distinguished from one with no storage.
3479        assert!(state
3480            .storage_range(B256::repeat_byte(0xee), B256::ZERO, B256::repeat_byte(0xff), 10_000)?
3481            .is_none());
3482
3483        Ok(())
3484    }
3485
3486    #[test]
3487    fn state_range_provider_proofs_start_at_the_real_root() -> eyre::Result<()> {
3488        let factory = test_provider_factory_with_genesis()?;
3489        let provider_rw = factory.provider_rw()?;
3490
3491        let (address, account) = random_account(1);
3492        let hashed_address = keccak256(address);
3493        let hashed_slot = keccak256(B256::with_last_byte(1));
3494        provider_rw.insert_account_for_hashing([(address, Some(account))])?;
3495        provider_rw.insert_storage_for_hashing([(
3496            address,
3497            [StorageEntry { key: B256::with_last_byte(1), value: U256::from(10) }],
3498        )])?;
3499        provider_rw.commit()?;
3500
3501        let provider = BlockchainProvider::new(factory)?;
3502
3503        // The first node of a sorted boundary proof is always the trie root, so this checks the
3504        // proof was generated against the real, current root rather than a stale or empty one.
3505        let state_root = provider.latest()?.state_root(HashedPostState::default())?;
3506        let state = provider.state_range_provider(EMPTY_ROOT_HASH)?.unwrap();
3507        let account_proof = state.account_range_proof(&[hashed_address])?;
3508        assert!(!account_proof.is_empty());
3509        assert_eq!(keccak256(&account_proof[0]), state_root);
3510
3511        let storage_root = state.storage_root_by_hash(hashed_address)?;
3512        let storage_proof = state.storage_range_proof(hashed_address, &[hashed_slot])?;
3513        assert!(!storage_proof.is_empty());
3514        assert_eq!(keccak256(&storage_proof[0]), storage_root);
3515
3516        Ok(())
3517    }
3518
3519    #[test]
3520    fn state_range_provider_serves_recent_root_and_rejects_expired_root() -> eyre::Result<()> {
3521        let mut rng = generators::rng();
3522        let factory = create_test_provider_factory();
3523        let provider_rw = factory.provider_rw()?;
3524        let expired_root = B256::repeat_byte(0x11);
3525        let recent_root = B256::repeat_byte(0x22);
3526        let mut parent = B256::ZERO;
3527
3528        for number in 0..=SNAPSHOT_STATE_RETENTION {
3529            let mut block = random_block(
3530                &mut rng,
3531                number,
3532                BlockParams { parent: Some(parent), tx_count: Some(0), ..Default::default() },
3533            )
3534            .unseal();
3535            block.header.state_root = match number {
3536                0 => expired_root,
3537                64 => recent_root,
3538                _ => EMPTY_ROOT_HASH,
3539            };
3540            let block = block.seal_slow();
3541            parent = block.hash();
3542            provider_rw
3543                .insert_block(&block.try_recover().expect("failed to seal block with senders"))?;
3544        }
3545        provider_rw.save_stage_checkpoint(
3546            StageId::Finish,
3547            StageCheckpoint::new(SNAPSHOT_STATE_RETENTION),
3548        )?;
3549        provider_rw.commit()?;
3550
3551        let provider = BlockchainProvider::new(factory.clone())?;
3552        assert!(provider.state_range_provider(recent_root)?.is_some());
3553        assert!(provider.state_range_provider(expired_root)?.is_none());
3554
3555        // An unverified snap attempt owns the state tables, so no root resolves.
3556        let mut attempt = SnapAttempt::start(None, BlockNumHash::default(), B256::ZERO);
3557        let provider_rw = factory.provider_rw()?;
3558        provider_rw.write_snap_attempt(&attempt)?;
3559        provider_rw.commit()?;
3560        assert!(provider.state_range_provider(recent_root)?.is_none());
3561
3562        attempt.verify();
3563        let provider_rw = factory.provider_rw()?;
3564        provider_rw.write_snap_attempt(&attempt)?;
3565        provider_rw.commit()?;
3566        assert!(provider.state_range_provider(recent_root)?.is_some());
3567
3568        // State executed past `Finish` matches no retained root.
3569        let provider_rw = factory.provider_rw()?;
3570        provider_rw.save_stage_checkpoint(
3571            StageId::Execution,
3572            StageCheckpoint::new(SNAPSHOT_STATE_RETENTION + 1),
3573        )?;
3574        provider_rw.commit()?;
3575        assert!(provider.state_range_provider(recent_root)?.is_none());
3576
3577        Ok(())
3578    }
3579
3580    #[test]
3581    fn state_range_provider_serves_persisted_root_with_in_memory_overlay() -> eyre::Result<()> {
3582        let mut rng = generators::rng();
3583
3584        // State A: one account, persisted at block 1. Block 1 is not the database head, so only
3585        // the persisted-history fallback can resolve its root.
3586        let (address, account_a) = random_account(1);
3587        let hashed_address = keccak256(address);
3588        let factory = test_provider_factory_with_genesis()?;
3589        let provider_rw = factory.provider_rw()?;
3590        provider_rw.insert_account_for_hashing([(address, Some(account_a.clone()))])?;
3591        provider_rw.commit()?;
3592        let persisted_root = factory.latest()?.state_root(HashedPostState::default())?;
3593
3594        let genesis_hash = factory.sealed_header(0)?.unwrap().hash();
3595        let mut persisted_block = random_block(
3596            &mut rng,
3597            1,
3598            BlockParams { parent: Some(genesis_hash), tx_count: Some(0), ..Default::default() },
3599        )
3600        .unseal();
3601        persisted_block.header.state_root = persisted_root;
3602        let persisted_block =
3603            persisted_block.seal_slow().try_recover().expect("failed to seal block with senders");
3604        let persisted_hash = persisted_block.hash();
3605
3606        let provider_rw = factory.provider_rw()?;
3607        provider_rw.insert_block(&persisted_block)?;
3608        provider_rw.save_stage_checkpoint(StageId::Finish, StageCheckpoint::new(1))?;
3609        provider_rw.commit()?;
3610
3611        // State B: block 2 changes the account and becomes the database head, with a root
3612        // different from block 1's.
3613        let account_b = Account { nonce: 2, balance: U256::from(2), ..account_a.clone() };
3614        let mut state_b = HashedPostState::default();
3615        state_b.accounts.insert(hashed_address, Some(account_b.clone()));
3616        let head_root = factory.latest()?.state_root(state_b.clone())?;
3617        assert_ne!(head_root, persisted_root);
3618
3619        let mut head_block = random_block(
3620            &mut rng,
3621            2,
3622            BlockParams { parent: Some(persisted_hash), tx_count: Some(0), ..Default::default() },
3623        )
3624        .unseal();
3625        head_block.header.state_root = head_root;
3626        let head_block =
3627            head_block.seal_slow().try_recover().expect("failed to seal block with senders");
3628        let head_hash = head_block.hash();
3629
3630        let provider_rw = factory.provider_rw()?;
3631        provider_rw.append_blocks_with_state(
3632            vec![head_block],
3633            &ExecutionOutcome {
3634                bundle: BundleState::new(
3635                    [(
3636                        address,
3637                        Some(account_a.clone().into()),
3638                        Some(account_b.into()),
3639                        Default::default(),
3640                    )],
3641                    [[(address, Some(Some(account_a.clone().into())), [])]],
3642                    [],
3643                ),
3644                first_block: 2,
3645                ..Default::default()
3646            },
3647            state_b.into_sorted(),
3648        )?;
3649        provider_rw.save_stage_checkpoint(StageId::Finish, StageCheckpoint::new(2))?;
3650        provider_rw.commit()?;
3651
3652        let provider = BlockchainProvider::new(factory)?;
3653
3654        // An in-memory block on top of the head adds another account under a root of its own.
3655        let (memory_address, memory_account) = random_account(3);
3656        let mut memory_state = HashedPostState::default();
3657        memory_state.accounts.insert(keccak256(memory_address), Some(memory_account));
3658
3659        let memory_root = B256::repeat_byte(0x77);
3660        assert_ne!(memory_root, persisted_root);
3661        let mut memory_block = random_block(
3662            &mut rng,
3663            3,
3664            BlockParams { parent: Some(head_hash), tx_count: Some(0), ..Default::default() },
3665        )
3666        .unseal();
3667        memory_block.header.state_root = memory_root;
3668        let memory_block =
3669            memory_block.seal_slow().try_recover().expect("failed to seal block with senders");
3670        let trie_data = SortedTrieData::new(
3671            Arc::new(memory_state.into_sorted()),
3672            Arc::new(TrieUpdates::default().into_sorted()),
3673        );
3674        let execution_output = BlockExecutionOutput {
3675            result: BlockExecutionResult {
3676                receipts: Default::default(),
3677                requests: Default::default(),
3678                gas_used: 0,
3679                blob_gas_used: 0,
3680            },
3681            state: Default::default(),
3682        };
3683        let executed =
3684            ExecutedBlock::new(Arc::new(memory_block), Arc::new(execution_output), trie_data);
3685        provider
3686            .canonical_in_memory_state
3687            .update_chain(NewCanonicalChain::Commit { new: vec![executed] });
3688
3689        // No in-memory block carries the persisted root, so the persisted-history fallback must
3690        // resolve it, ignoring both the later database block and the in-memory block above it.
3691        assert!(!provider
3692            .canonical_in_memory_state
3693            .canonical_chain()
3694            .any(|state| state.state_root() == persisted_root));
3695        let state =
3696            provider.state_range_provider(persisted_root)?.expect("persisted root must resolve");
3697        let range = state.account_range(B256::ZERO, B256::repeat_byte(0xff), 10_000)?;
3698        assert_eq!(range.items, vec![(hashed_address, account_a)]);
3699
3700        // The first node of a boundary proof is the trie root, so this is the root the view
3701        // reports.
3702        let proof = state.account_range_proof(&[hashed_address])?;
3703        assert!(!proof.is_empty());
3704        assert_eq!(keccak256(&proof[0]), persisted_root);
3705
3706        Ok(())
3707    }
3708
3709    #[test]
3710    fn latest_reads_in_memory_state_like_the_hash_lookup() -> eyre::Result<()> {
3711        use crate::{AccountReader, StateProvider, StateProviderBox};
3712        use reth_storage_api::DatabaseProviderROFactory;
3713        use reth_storage_overlay::OverlayStateProviderFactory;
3714
3715        let mut rng = generators::rng();
3716        let factory = test_provider_factory_with_genesis()?;
3717        let provider = BlockchainProvider::new(factory)?;
3718        let genesis = provider.canonical_in_memory_state.get_canonical_head();
3719
3720        let (address, account) = random_account(1);
3721        let hashed_address = keccak256(address);
3722        let slot_key = B256::with_last_byte(1);
3723        let slot = U256::from_be_bytes(slot_key.0);
3724        let value = U256::from(42);
3725
3726        let mut hashed_state = HashedPostState::default();
3727        hashed_state.accounts.insert(hashed_address, Some(account.clone()));
3728        hashed_state
3729            .storages
3730            .insert(hashed_address, HashedStorage::from_iter([(keccak256(slot_key), value)]));
3731
3732        let mut storage = HashMap::default();
3733        storage.insert(slot, (U256::ZERO, value));
3734
3735        let block = random_block(
3736            &mut rng,
3737            genesis.number + 1,
3738            BlockParams { parent: Some(genesis.hash()), tx_count: Some(0), ..Default::default() },
3739        )
3740        .try_recover()
3741        .expect("failed to seal block with senders");
3742        let block_hash = block.hash();
3743
3744        let execution_output = BlockExecutionOutput {
3745            result: BlockExecutionResult {
3746                receipts: Default::default(),
3747                requests: Default::default(),
3748                gas_used: 0,
3749                blob_gas_used: 0,
3750            },
3751            state: BundleState::new(
3752                [(address, None, Some(account.clone().into()), storage)],
3753                [[(address, Some(None), [])]],
3754                [],
3755            ),
3756        };
3757        let executed = ExecutedBlock::new(
3758            Arc::new(block),
3759            Arc::new(execution_output),
3760            SortedTrieData::new(
3761                Arc::new(hashed_state.into_sorted()),
3762                Arc::new(TrieUpdates::default().into_sorted()),
3763            ),
3764        );
3765        provider
3766            .canonical_in_memory_state
3767            .update_chain(NewCanonicalChain::Commit { new: vec![executed] });
3768
3769        // `latest` reuses the canonical `Arc<BlockState>` chain, while the hash-based lookup
3770        // rebuilds an equivalent chain from the overlay manager's block graph. Both must observe
3771        // the same in-memory account and storage values.
3772        let rebuilt_from_hash = OverlayStateProviderFactory::new(
3773            provider.database.clone(),
3774            provider.database.overlay_manager().overlay_builder(block_hash),
3775        )
3776        .database_provider_ro()?;
3777
3778        for state in [
3779            Box::new(rebuilt_from_hash) as StateProviderBox,
3780            provider.latest()?,
3781            provider.state_by_block_hash(block_hash)?,
3782        ] {
3783            assert_eq!(state.basic_account(&address)?, Some(account.clone()));
3784            assert_eq!(state.storage(address, slot_key)?, Some(value));
3785        }
3786
3787        Ok(())
3788    }
3789
3790    #[test]
3791    fn state_range_provider_reverts_database_advancement_past_anchor() -> eyre::Result<()> {
3792        let mut rng = generators::rng();
3793        let factory = test_provider_factory_with_genesis()?;
3794        let provider = BlockchainProvider::new(factory)?;
3795        let genesis = provider.canonical_in_memory_state.get_canonical_head();
3796
3797        // In-memory target block anchored on genesis, with a known account.
3798        let (target_address, target_account) = random_account(1);
3799        let target_hashed = keccak256(target_address);
3800        let mut target_state = HashedPostState::default();
3801        target_state.accounts.insert(target_hashed, Some(target_account.clone()));
3802
3803        let unique_root = B256::repeat_byte(0x77);
3804        let mut block = random_block(
3805            &mut rng,
3806            genesis.number + 1,
3807            BlockParams { parent: Some(genesis.hash()), tx_count: Some(0), ..Default::default() },
3808        )
3809        .unseal();
3810        block.header.state_root = unique_root;
3811        let block = block.seal_slow().try_recover().expect("failed to seal block with senders");
3812        let trie_data = SortedTrieData::new(
3813            Arc::new(target_state.into_sorted()),
3814            Arc::new(TrieUpdates::default().into_sorted()),
3815        );
3816        let execution_output = BlockExecutionOutput {
3817            result: BlockExecutionResult {
3818                receipts: Default::default(),
3819                requests: Default::default(),
3820                gas_used: 0,
3821                blob_gas_used: 0,
3822            },
3823            state: Default::default(),
3824        };
3825        let executed = ExecutedBlock::new(Arc::new(block), Arc::new(execution_output), trie_data);
3826        provider
3827            .canonical_in_memory_state
3828            .update_chain(NewCanonicalChain::Commit { new: vec![executed] });
3829
3830        // Persistence races ahead: a *different* block, with a *different* account, lands in
3831        // the database on top of the same genesis anchor while the in-memory chain above still
3832        // references genesis as its anchor.
3833        let (noise_address, noise_account) = random_account(2);
3834        let noise_block = random_block(
3835            &mut rng,
3836            genesis.number + 1,
3837            BlockParams { parent: Some(genesis.hash()), tx_count: Some(0), ..Default::default() },
3838        )
3839        .try_recover()
3840        .expect("failed to seal block with senders");
3841        let mut noise_state = HashedPostState::default();
3842        noise_state.accounts.insert(keccak256(noise_address), Some(noise_account.clone()));
3843        let provider_rw = provider.database.provider_rw()?;
3844        provider_rw.append_blocks_with_state(
3845            vec![noise_block],
3846            &ExecutionOutcome {
3847                bundle: BundleState::new(
3848                    [(noise_address, None, Some(noise_account.into()), Default::default())],
3849                    [[(noise_address, Some(None), [])]],
3850                    [],
3851                ),
3852                first_block: genesis.number + 1,
3853                ..Default::default()
3854            },
3855            noise_state.into_sorted(),
3856        )?;
3857        provider_rw
3858            .save_stage_checkpoint(StageId::Finish, StageCheckpoint::new(genesis.number + 1))?;
3859        provider_rw.commit()?;
3860
3861        // Resolving the in-memory root must revert the database's advancement back to genesis,
3862        // so the noise account must not leak into the result.
3863        let state =
3864            provider.state_range_provider(unique_root)?.expect("in-memory root must resolve");
3865        let range = state.account_range(B256::ZERO, B256::repeat_byte(0xff), 10_000)?;
3866        assert_eq!(range.items, vec![(target_hashed, target_account)]);
3867
3868        Ok(())
3869    }
3870
3871    #[test]
3872    fn historical_state_range_provider_reverts_state_change_past_retained_anchor(
3873    ) -> eyre::Result<()> {
3874        let mut rng = generators::rng();
3875
3876        // State A: the account and its one storage slot as of the retained anchor.
3877        let (address, account_a) = random_account(1);
3878        let hashed_address = keccak256(address);
3879        let slot_key = B256::with_last_byte(1);
3880        let slot = U256::from_be_bytes(slot_key.0);
3881        let hashed_slot = keccak256(slot_key);
3882        let value_a = U256::ONE;
3883
3884        let factory = test_provider_factory_with_genesis()?;
3885        let provider_rw = factory.provider_rw()?;
3886        provider_rw.insert_account_for_hashing([(address, Some(account_a.clone()))])?;
3887        provider_rw.insert_storage_for_hashing([(
3888            address,
3889            [StorageEntry { key: slot_key, value: value_a }],
3890        )])?;
3891        provider_rw.commit()?;
3892        let anchor_root = factory.latest()?.state_root(HashedPostState::default())?;
3893
3894        let genesis_hash = factory.sealed_header(0)?.unwrap().hash();
3895        let mut anchor_block = random_block(
3896            &mut rng,
3897            1,
3898            BlockParams { parent: Some(genesis_hash), tx_count: Some(0), ..Default::default() },
3899        )
3900        .unseal();
3901        anchor_block.header.state_root = anchor_root;
3902        let anchor_block =
3903            anchor_block.seal_slow().try_recover().expect("failed to seal block with senders");
3904        let anchor_hash = anchor_block.hash();
3905
3906        let provider_rw = factory.provider_rw()?;
3907        provider_rw.insert_block(&anchor_block)?;
3908        provider_rw.save_stage_checkpoint(StageId::Finish, StageCheckpoint::new(1))?;
3909        provider_rw.commit()?;
3910
3911        // State B: a later block changes both the account and its storage slot.
3912        let account_b = Account { nonce: 2, balance: U256::from(2), ..account_a.clone() };
3913        let value_b = U256::from(2);
3914
3915        let mut storage = HashMap::default();
3916        storage.insert(slot, (value_a, value_b));
3917
3918        let mut state_b = HashedPostState::default();
3919        state_b.accounts.insert(hashed_address, Some(account_b.clone()));
3920        state_b.storages.insert(hashed_address, HashedStorage::from_iter([(hashed_slot, value_b)]));
3921
3922        let state_b_root = factory.latest()?.state_root(state_b.clone())?;
3923        let mut later_block = random_block(
3924            &mut rng,
3925            2,
3926            BlockParams { parent: Some(anchor_hash), tx_count: Some(0), ..Default::default() },
3927        )
3928        .unseal();
3929        later_block.header.state_root = state_b_root;
3930        let later_block =
3931            later_block.seal_slow().try_recover().expect("failed to seal block with senders");
3932
3933        let provider_rw = factory.provider_rw()?;
3934        provider_rw.append_blocks_with_state(
3935            vec![later_block],
3936            &ExecutionOutcome {
3937                bundle: BundleState::new(
3938                    [(address, Some(account_a.clone().into()), Some(account_b.into()), storage)],
3939                    [[(address, Some(Some(account_a.clone().into())), [(slot, value_a)])]],
3940                    [],
3941                ),
3942                first_block: 2,
3943                ..Default::default()
3944            },
3945            state_b.into_sorted(),
3946        )?;
3947        provider_rw.save_stage_checkpoint(StageId::Finish, StageCheckpoint::new(2))?;
3948        provider_rw.commit()?;
3949
3950        // Resolving the anchor root must revert the later account and storage changes; state B
3951        // must not leak into the response.
3952        let provider = BlockchainProvider::new(factory)?;
3953        let state =
3954            provider.state_range_provider(anchor_root)?.expect("retained root must resolve");
3955        let range = state.account_range(B256::ZERO, B256::repeat_byte(0xff), 10_000)?;
3956        assert_eq!(range.items, vec![(hashed_address, account_a)]);
3957
3958        let storage_range = state
3959            .storage_range(hashed_address, B256::ZERO, B256::repeat_byte(0xff), 10_000)?
3960            .expect("account must have storage");
3961        assert_eq!(storage_range.items, vec![(hashed_slot, value_a)]);
3962
3963        Ok(())
3964    }
3965
3966    #[test]
3967    fn get_state_preserves_empty_block_receipts() -> eyre::Result<()> {
3968        let mut rng = generators::rng();
3969        let factory = create_test_provider_factory();
3970        let writer = factory.provider_rw()?;
3971        let mut parent = B256::ZERO;
3972        let mut expected = Vec::new();
3973        // Persist empty blocks before receipt zero, between transactions and at the tip.
3974        for (number, tx_count) in [0, 0, 1, 0, 1, 0].into_iter().enumerate() {
3975            let block = random_block(
3976                &mut rng,
3977                number as u64,
3978                BlockParams {
3979                    parent: Some(parent),
3980                    tx_count: Some(tx_count),
3981                    ..Default::default()
3982                },
3983            )
3984            .try_recover()
3985            .expect("failed to recover test block");
3986            parent = block.hash();
3987            expected.push(
3988                block
3989                    .body()
3990                    .transactions
3991                    .iter()
3992                    .map(|tx| random_receipt(&mut rng, tx, Some(0), Some(0)))
3993                    .collect::<Vec<_>>(),
3994            );
3995            writer.insert_block(&block)?;
3996        }
3997        writer.write_state(
3998            &ExecutionOutcome { first_block: 0, receipts: expected.clone(), ..Default::default() },
3999            OriginalValuesKnown::No,
4000            StateWriteConfig::default(),
4001        )?;
4002        writer.save_stage_checkpoint(StageId::Finish, StageCheckpoint::new(5))?;
4003        writer.commit()?;
4004
4005        let provider = BlockchainProvider::new(factory)?;
4006        assert!(provider.canonical_in_memory_state.head_state().is_none());
4007        assert!(provider.receipt(0)?.is_some());
4008        for (number, receipts) in expected.into_iter().enumerate() {
4009            let outcome = provider.get_state(number as u64)?.expect("persisted block state");
4010            assert_eq!(outcome.receipts, vec![receipts], "block {number}");
4011        }
4012        Ok(())
4013    }
4014
4015    #[test]
4016    fn providers_of_one_factory_share_in_memory_blocks() -> eyre::Result<()> {
4017        let factory = test_provider_factory_with_genesis()?;
4018        let provider = BlockchainProvider::new(factory.clone())?;
4019        let other = BlockchainProvider::new(factory)?;
4020        let genesis = provider.canonical_in_memory_state.get_canonical_head();
4021        let block = TestBlockBuilder::eth().get_executed_block_with_number(1, genesis.hash());
4022        let hash = block.recovered_block().hash();
4023
4024        provider
4025            .canonical_in_memory_state
4026            .update_chain(NewCanonicalChain::Commit { new: vec![block] });
4027
4028        assert!(other.canonical_in_memory_state.state_by_hash(hash).is_some());
4029        Ok(())
4030    }
4031}