Skip to main content

reth_chain_state/in_memory/
canonical.rs

1use super::{
2    blocks::{InMemoryBlocks, InMemoryBlocksStats},
3    BlockState, ExecutedBlock, NewCanonicalChain,
4};
5use crate::{
6    CanonStateNotification, CanonStateNotificationSender, CanonStateNotifications,
7    ChainInfoHeaders, ChainInfoTracker,
8};
9use alloy_consensus::transaction::TransactionMeta;
10use alloy_eips::BlockNumHash;
11use alloy_primitives::{map::B256Map, BlockNumber, TxHash, B256};
12use parking_lot::RwLock;
13use reth_chainspec::ChainInfo;
14use reth_ethereum_primitives::EthPrimitives;
15use reth_execution_types::RecoveredBlockAndExecutionOutput;
16use reth_metrics::{metrics::Gauge, Metrics};
17use reth_primitives_traits::{
18    BlockBody as _, NodePrimitives, RecoveredBlock, SealedBlock, SealedHeader,
19};
20use std::{
21    collections::BTreeMap,
22    sync::{
23        atomic::{AtomicU64, Ordering},
24        Arc,
25    },
26    time::Instant,
27};
28use tokio::sync::{broadcast, watch};
29
30/// Size of the broadcast channel used to notify canonical state events.
31const CANON_STATE_NOTIFICATION_CHANNEL_SIZE: usize = 256;
32
33/// Metrics for the in-memory state.
34#[derive(Metrics)]
35#[metrics(scope = "blockchain_tree.in_mem_state")]
36pub(crate) struct InMemoryStateMetrics {
37    /// The block number of the earliest block in the in-memory state.
38    pub(crate) earliest_block: Gauge,
39    /// The block number of the latest block in the in-memory state.
40    pub(crate) latest_block: Gauge,
41    /// The number of blocks in the in-memory state.
42    pub(crate) num_blocks: Gauge,
43}
44
45/// Container type for in memory state data of the executed blocks that are not on disk yet.
46///
47/// This tracks blocks and their state that haven't been persisted to disk yet: the blocks that
48/// are part of the canonical chain that can be traced back to a canonical block on disk, and the
49/// executed blocks that are not canonical.
50///
51/// A node has one in-memory state. Clones are handles to the same blocks, pending block and
52/// metrics, and the default value is an empty state of its own.
53///
54/// # Locking behavior on state updates
55///
56/// Updates change the blocks, the numbers and the pending block under one write lock. This
57/// prevents readers from observing partially updated state where they are out of sync with each
58/// other, or a block that is both canonical and not canonical, or neither.
59#[derive(Debug, Clone, Default)]
60pub struct InMemoryState<N: NodePrimitives = EthPrimitives> {
61    inner: Arc<InMemoryStateInner<N>>,
62}
63
64impl<N: NodePrimitives> InMemoryState<N> {
65    pub(crate) fn new(
66        blocks: B256Map<Arc<BlockState<N>>>,
67        numbers: BTreeMap<u64, B256>,
68        pending: Option<BlockState<N>>,
69    ) -> Self {
70        let this = Self {
71            inner: Arc::new(InMemoryStateInner {
72                blocks: RwLock::new(InMemoryBlocks::new(blocks, numbers, pending)),
73                removal_generation: Default::default(),
74                metrics: Default::default(),
75            }),
76        };
77        this.update_metrics();
78        this
79    }
80
81    /// Update the metrics for the in-memory state.
82    ///
83    /// # Locking behavior
84    ///
85    /// This tries to acquire a read lock. Drop any write locks before calling this.
86    pub(crate) fn update_metrics(&self) {
87        let stats = self.inner.blocks.read().stats();
88        self.record_metrics(stats);
89    }
90
91    /// Sets the in-memory state metrics from `stats`.
92    fn record_metrics(&self, stats: InMemoryBlocksStats) {
93        let InMemoryBlocksStats { count, earliest, latest } = stats;
94        if let Some(earliest_block_number) = earliest {
95            self.inner.metrics.earliest_block.set(earliest_block_number as f64);
96        }
97        if let Some(latest_block_number) = latest {
98            self.inner.metrics.latest_block.set(latest_block_number as f64);
99        }
100        self.inner.metrics.num_blocks.set(count as f64);
101    }
102
103    /// Returns the state of the tracked block with the given hash, canonical or not.
104    pub fn state_by_hash(&self, hash: B256) -> Option<Arc<BlockState<N>>> {
105        self.inner.blocks.read().get(&hash).cloned()
106    }
107
108    /// Returns `true` if a block with the given hash is tracked, canonical or not.
109    pub fn contains(&self, hash: &B256) -> bool {
110        self.inner.blocks.read().contains(hash)
111    }
112
113    /// Returns the numbers of tracked canonical blocks and of tracked blocks that are not
114    /// canonical, both taken from the same snapshot of the blocks.
115    pub fn block_counts(&self) -> InMemoryStateBlockCounts {
116        self.inner.blocks.read().counts()
117    }
118
119    /// Returns the state for a given block number.
120    pub(crate) fn state_by_number(&self, number: u64) -> Option<Arc<BlockState<N>>> {
121        self.inner.blocks.read().canonical().by_number(number).cloned()
122    }
123
124    /// Returns the hash for a specific block number
125    pub(crate) fn hash_by_number(&self, number: u64) -> Option<B256> {
126        self.inner.blocks.read().canonical().hash_by_number(number)
127    }
128
129    /// Returns the current chain head state.
130    pub(crate) fn head_state(&self) -> Option<Arc<BlockState<N>>> {
131        self.inner.blocks.read().canonical().head().cloned()
132    }
133
134    /// Returns the pending state corresponding to the current head plus one,
135    /// from the payload received in newPayload that does not have a FCU yet.
136    pub(crate) fn pending_state(&self) -> Option<Arc<BlockState<N>>> {
137        self.inner.blocks.read().pending_state().cloned()
138    }
139
140    /// Returns a counter that increases every time blocks are removed.
141    ///
142    /// State derived from the tracked blocks compares it with the value it saw last to learn that
143    /// blocks it refers to may no longer be tracked.
144    pub fn removal_generation(&self) -> u64 {
145        self.inner.removal_generation.load(Ordering::Relaxed)
146    }
147
148    #[cfg(test)]
149    fn block_count(&self) -> usize {
150        self.inner.blocks.read().canonical().len()
151    }
152
153    /// Applies `f` to the blocks under the write lock, bumps the removal generation if `f`
154    /// removed blocks, and updates the metrics from the stats read under the same lock.
155    ///
156    /// Returns what `f` returns, so that the blocks it removed are dropped after the lock is
157    /// released.
158    fn update<R>(&self, f: impl FnOnce(&mut InMemoryBlocks<N>) -> R) -> R {
159        let (result, stats) = {
160            let mut blocks = self.inner.blocks.write();
161            let removed_count = blocks.removed_count();
162            let result = f(&mut blocks);
163            #[cfg(debug_assertions)]
164            blocks.assert_invariants();
165            if blocks.removed_count() != removed_count {
166                self.inner.removal_generation.fetch_add(1, Ordering::Relaxed);
167            }
168            (result, blocks.stats())
169        };
170        self.record_metrics(stats);
171        result
172    }
173}
174
175/// The blocks of an [`InMemoryState`] with their lock, and what is derived from them.
176#[derive(Debug, Default)]
177struct InMemoryStateInner<N: NodePrimitives> {
178    /// The executed blocks that are not on disk yet, canonical or not.
179    blocks: RwLock<InMemoryBlocks<N>>,
180    /// Counts the updates that removed blocks.
181    removal_generation: AtomicU64,
182    /// Metrics for the in-memory state.
183    metrics: InMemoryStateMetrics,
184}
185
186/// The numbers of blocks an [`InMemoryState`] tracks.
187#[derive(Debug, Clone, Copy, PartialEq, Eq)]
188pub struct InMemoryStateBlockCounts {
189    /// The number of canonical blocks.
190    pub canonical: usize,
191    /// The number of executed blocks that are not canonical, including the pending block.
192    pub non_canonical: usize,
193}
194
195/// Inner type to provide in memory state. It includes a chain tracker to be
196/// advanced internally by the tree.
197#[derive(Debug)]
198pub(crate) struct CanonicalInMemoryStateInner<N: NodePrimitives> {
199    /// Tracks certain chain information, such as the canonical head, safe head, and finalized
200    /// head.
201    pub(crate) chain_info_tracker: ChainInfoTracker<N>,
202    /// Tracks blocks at the tip of the chain that have not been persisted to disk yet.
203    pub(crate) in_memory_state: InMemoryState<N>,
204    /// A broadcast stream that emits events when the canonical chain is updated.
205    pub(crate) canon_state_notification_sender: CanonStateNotificationSender<N>,
206}
207
208impl<N: NodePrimitives> CanonicalInMemoryStateInner<N> {
209    /// Clears all entries in the in memory state.
210    fn clear(&self) {
211        self.in_memory_state.update(InMemoryBlocks::clear);
212    }
213}
214
215/// This type is responsible for providing the blocks, receipts, and state for
216/// all canonical blocks not on disk yet and keeps track of the block range that
217/// is in memory.
218#[derive(Debug, Clone)]
219pub struct CanonicalInMemoryState<N: NodePrimitives = EthPrimitives> {
220    pub(crate) inner: Arc<CanonicalInMemoryStateInner<N>>,
221}
222
223impl<N: NodePrimitives> CanonicalInMemoryState<N> {
224    /// Create a new in-memory state with the given blocks, numbers, pending state, and optional
225    /// finalized header.
226    pub fn new(
227        blocks: B256Map<Arc<BlockState<N>>>,
228        numbers: BTreeMap<u64, B256>,
229        pending: Option<BlockState<N>>,
230        finalized: Option<SealedHeader<N::BlockHeader>>,
231        safe: Option<SealedHeader<N::BlockHeader>>,
232    ) -> Self {
233        let in_memory_state = InMemoryState::new(blocks, numbers, pending);
234        let header = in_memory_state.head_state().map_or_else(SealedHeader::default, |state| {
235            state.block_ref().recovered_block().clone_sealed_header()
236        });
237        let chain_info_tracker =
238            ChainInfoTracker::new(ChainInfoHeaders { canonical_head: header, safe, finalized });
239        let (canon_state_notification_sender, _) =
240            broadcast::channel(CANON_STATE_NOTIFICATION_CHANNEL_SIZE);
241
242        Self {
243            inner: Arc::new(CanonicalInMemoryStateInner {
244                chain_info_tracker,
245                in_memory_state,
246                canon_state_notification_sender,
247            }),
248        }
249    }
250
251    /// Create an empty state.
252    pub fn empty() -> Self {
253        Self::new(B256Map::default(), BTreeMap::new(), None, None, None)
254    }
255
256    /// Creates a canonical state over the blocks of `in_memory_state`, with the canonical head
257    /// and the safe and finalized blocks of `chain_info_headers`.
258    ///
259    /// The blocks are shared with every other handle of `in_memory_state`, so an update of the
260    /// blocks through the returned value is visible through all of them. The chain info and the
261    /// notifications belong to the returned value and its clones.
262    pub fn with_head(
263        chain_info_headers: ChainInfoHeaders<N::BlockHeader>,
264        in_memory_state: InMemoryState<N>,
265    ) -> Self {
266        let chain_info_tracker = ChainInfoTracker::new(chain_info_headers);
267        let (canon_state_notification_sender, _) =
268            broadcast::channel(CANON_STATE_NOTIFICATION_CHANNEL_SIZE);
269        let inner = CanonicalInMemoryStateInner {
270            chain_info_tracker,
271            in_memory_state,
272            canon_state_notification_sender,
273        };
274
275        Self { inner: Arc::new(inner) }
276    }
277
278    /// Returns the block hash corresponding to the given number.
279    pub fn hash_by_number(&self, number: u64) -> Option<B256> {
280        self.inner.in_memory_state.hash_by_number(number)
281    }
282
283    /// Returns the header corresponding to the given hash.
284    pub fn header_by_hash(&self, hash: B256) -> Option<SealedHeader<N::BlockHeader>> {
285        self.state_by_hash(hash)
286            .map(|block| block.block_ref().recovered_block().clone_sealed_header())
287    }
288
289    /// Clears all entries in the in memory state.
290    pub fn clear_state(&self) {
291        self.inner.clear()
292    }
293
294    /// Tracks an executed block that is not canonical, unless it is already tracked.
295    ///
296    /// The block is connected to its parent block, canonical or not. It is not returned by the
297    /// canonical lookups until [`Self::update_chain`] makes it canonical. Does not change the
298    /// pending block.
299    pub fn insert_executed(&self, block: ExecutedBlock<N>) {
300        self.inner.in_memory_state.update(|blocks| blocks.insert_executed(block));
301    }
302
303    /// Updates the pending block with the given block, and tracks it like
304    /// [`Self::insert_executed`].
305    ///
306    /// Note: This assumes that the parent block of the pending block is canonical.
307    pub fn set_pending_block(&self, pending: ExecutedBlock<N>) {
308        self.inner.in_memory_state.update(|blocks| blocks.insert_pending(pending));
309    }
310
311    /// Update the in memory state with the given chain update.
312    ///
313    /// This appends the new blocks to the tracked chain and connects them to their parent blocks.
314    /// The blocks a reorg replaced stay tracked as executed blocks that are not canonical, and so
315    /// does the pending block, which is no longer pending.
316    pub fn update_chain(&self, new_chain: NewCanonicalChain<N>) {
317        self.inner.in_memory_state.update(|blocks| blocks.update_chain(new_chain));
318    }
319
320    /// Applies a backfill sync that finished at `backfill` without unwinding, in one update.
321    ///
322    /// Removes the canonical blocks up to and including its height like
323    /// [`Self::remove_canonical_until`], makes every remaining canonical block an executed block
324    /// that is not canonical, and removes the executed blocks that conflict with `backfill` like
325    /// [`Self::prune_conflicting_with_finalized`]. Afterwards there is no pending block.
326    ///
327    /// If the canonical block at the height of `backfill` is another block, the canonical blocks
328    /// are only removed as conflicting blocks, together with the blocks built on that block.
329    pub fn on_backfill_finished(&self, persisted_hash: B256, backfill: BlockNumHash) {
330        self.inner.in_memory_state.update(|blocks| {
331            let removed = if blocks
332                .canonical()
333                .hash_by_number(backfill.number)
334                .is_none_or(|hash| hash == backfill.hash)
335            {
336                blocks.remove_canonical_until(persisted_hash, backfill.number)
337            } else {
338                Vec::new()
339            };
340            blocks.demote_canonical_chain();
341            (removed, blocks.prune_conflicting_with_finalized(backfill))
342        });
343    }
344
345    /// Applies the persistence of blocks.
346    ///
347    /// Reports `last_persisted_block` as the persisted tip, and then removes blocks in one update:
348    /// the canonical blocks up to and including `state_trie_persisted_block` like
349    /// [`Self::remove_persisted_blocks_until`].
350    /// It also removes the executed blocks that are not canonical and whose chain builds on a
351    /// block above `last_persisted_block`: that block was removed from disk and is not tracked, so
352    /// they are not connected to the persisted chain anymore.
353    /// If there is a `finalized` block, it also removes the executed blocks that conflict with it
354    /// like [`Self::prune_conflicting_with_finalized`]. A finalized block above
355    /// `state_trie_persisted_block` is replaced by that block, so that only the blocks that
356    /// conflict with the persisted chain are removed.
357    pub fn on_blocks_persisted(
358        &self,
359        last_persisted_block: BlockNumHash,
360        state_trie_persisted_block: BlockNumHash,
361        finalized: Option<BlockNumHash>,
362    ) {
363        self.set_persisted(last_persisted_block);
364        self.inner.in_memory_state.update(|blocks| {
365            let removed = blocks.remove_canonical_until(
366                last_persisted_block.hash,
367                state_trie_persisted_block.number.min(last_persisted_block.number),
368            );
369            let disconnected = blocks.prune_built_above(last_persisted_block.number);
370            let pruned = finalized.map(|finalized| {
371                blocks.prune_conflicting_with_finalized(
372                    if state_trie_persisted_block.number < finalized.number {
373                        state_trie_persisted_block
374                    } else {
375                        finalized
376                    },
377                )
378            });
379            (removed, disconnected, pruned)
380        });
381    }
382
383    /// Removes the executed blocks that are not canonical and can no longer become canonical once
384    /// `finalized` is final: the ones below its height, the other ones at its height, and every
385    /// block built on such a block at its height.
386    pub fn prune_conflicting_with_finalized(&self, finalized: BlockNumHash) {
387        self.inner
388            .in_memory_state
389            .update(|blocks| blocks.prune_conflicting_with_finalized(finalized));
390    }
391
392    /// Removes blocks from the in memory state that are persisted to the given height.
393    ///
394    /// This will update the links between blocks and remove all blocks that are [..
395    /// `persisted_height`].
396    pub fn remove_persisted_blocks(&self, persisted_num_hash: BlockNumHash) {
397        self.remove_persisted_blocks_until(persisted_num_hash, persisted_num_hash.number);
398    }
399
400    /// Removes blocks from the in-memory state through `remove_until` while still reporting the
401    /// provided block as the persisted tip.
402    ///
403    /// Blocks above the persisted block are never removed, and the pending block is kept. If the
404    /// persisted block is neither a canonical in-memory block nor the block the in-memory
405    /// canonical chain builds on, it is still reported as the persisted tip, but no blocks are
406    /// removed.
407    pub fn remove_persisted_blocks_until(
408        &self,
409        persisted_num_hash: BlockNumHash,
410        remove_until: BlockNumber,
411    ) {
412        self.set_persisted(persisted_num_hash);
413        self.remove_canonical_until(
414            persisted_num_hash.hash,
415            remove_until.min(persisted_num_hash.number),
416        );
417    }
418
419    /// Removes the canonical blocks up to and including `remove_until` if `persisted_hash` is a
420    /// canonical in-memory block or the block the in-memory canonical chain builds on.
421    ///
422    /// Otherwise the canonical blocks in memory are not the ones that were persisted, and nothing
423    /// is removed. The chain info is unchanged.
424    pub fn remove_canonical_until(&self, persisted_hash: B256, remove_until: BlockNumber) {
425        self.inner
426            .in_memory_state
427            .update(|blocks| blocks.remove_canonical_until(persisted_hash, remove_until));
428    }
429
430    /// Returns in memory state corresponding the given hash.
431    pub fn state_by_hash(&self, hash: B256) -> Option<Arc<BlockState<N>>> {
432        self.inner.in_memory_state.inner.blocks.read().canonical().get(&hash).cloned()
433    }
434
435    /// Returns in memory state corresponding the block number.
436    pub fn state_by_number(&self, number: u64) -> Option<Arc<BlockState<N>>> {
437        self.inner.in_memory_state.state_by_number(number)
438    }
439
440    /// Returns the in memory head state.
441    pub fn head_state(&self) -> Option<Arc<BlockState<N>>> {
442        self.inner.in_memory_state.head_state()
443    }
444
445    /// Returns the in memory pending state.
446    pub fn pending_state(&self) -> Option<Arc<BlockState<N>>> {
447        self.inner.in_memory_state.pending_state()
448    }
449
450    /// Returns the in memory pending `BlockNumHash`.
451    pub fn pending_block_num_hash(&self) -> Option<BlockNumHash> {
452        self.inner
453            .in_memory_state
454            .pending_state()
455            .map(|state| BlockNumHash { number: state.number(), hash: state.hash() })
456    }
457
458    /// Returns the current `ChainInfo`.
459    pub fn chain_info(&self) -> ChainInfo {
460        self.inner.chain_info_tracker.chain_info()
461    }
462
463    /// Returns the latest canonical block number.
464    pub fn get_canonical_block_number(&self) -> u64 {
465        self.inner.chain_info_tracker.get_canonical_block_number()
466    }
467
468    /// Returns the `BlockNumHash` of the safe head.
469    pub fn get_safe_num_hash(&self) -> Option<BlockNumHash> {
470        self.inner.chain_info_tracker.get_safe_num_hash()
471    }
472
473    /// Returns the `BlockNumHash` of the finalized head.
474    pub fn get_finalized_num_hash(&self) -> Option<BlockNumHash> {
475        self.inner.chain_info_tracker.get_finalized_num_hash()
476    }
477
478    /// Hook for new fork choice update.
479    pub fn on_forkchoice_update_received(&self) {
480        self.inner.chain_info_tracker.on_forkchoice_update_received();
481    }
482
483    /// Returns the timestamp of the last received update.
484    pub fn last_received_update_timestamp(&self) -> Option<Instant> {
485        self.inner.chain_info_tracker.last_forkchoice_update_received_at()
486    }
487
488    /// Canonical head setter.
489    pub fn set_canonical_head(&self, header: SealedHeader<N::BlockHeader>) {
490        self.inner.chain_info_tracker.set_canonical_head(header);
491    }
492
493    /// Safe head setter.
494    pub fn set_safe(&self, header: SealedHeader<N::BlockHeader>) {
495        self.inner.chain_info_tracker.set_safe(header);
496    }
497
498    /// Finalized head setter.
499    pub fn set_finalized(&self, header: SealedHeader<N::BlockHeader>) {
500        self.inner.chain_info_tracker.set_finalized(header);
501    }
502
503    /// Persisted block setter.
504    pub fn set_persisted(&self, num_hash: BlockNumHash) {
505        self.inner.chain_info_tracker.set_persisted(num_hash);
506    }
507
508    /// Canonical head getter.
509    pub fn get_canonical_head(&self) -> SealedHeader<N::BlockHeader> {
510        self.inner.chain_info_tracker.get_canonical_head()
511    }
512
513    /// Finalized header getter.
514    pub fn get_finalized_header(&self) -> Option<SealedHeader<N::BlockHeader>> {
515        self.inner.chain_info_tracker.get_finalized_header()
516    }
517
518    /// Safe header getter.
519    pub fn get_safe_header(&self) -> Option<SealedHeader<N::BlockHeader>> {
520        self.inner.chain_info_tracker.get_safe_header()
521    }
522
523    /// Persisted block `BlockNumHash` getter.
524    pub fn get_persisted_num_hash(&self) -> Option<BlockNumHash> {
525        self.inner.chain_info_tracker.get_persisted_num_hash()
526    }
527
528    /// Returns the `SealedHeader` corresponding to the pending state.
529    pub fn pending_sealed_header(&self) -> Option<SealedHeader<N::BlockHeader>> {
530        self.pending_state().map(|h| h.block_ref().recovered_block().clone_sealed_header())
531    }
532
533    /// Returns the `Header` corresponding to the pending state.
534    pub fn pending_header(&self) -> Option<N::BlockHeader> {
535        self.pending_sealed_header().map(|sealed_header| sealed_header.unseal())
536    }
537
538    /// Returns the `SealedBlock` corresponding to the pending state.
539    pub fn pending_block(&self) -> Option<SealedBlock<N::Block>> {
540        self.pending_state()
541            .map(|block_state| block_state.block_ref().recovered_block().sealed_block().clone())
542    }
543
544    /// Returns the `RecoveredBlock` corresponding to the pending state.
545    pub fn pending_recovered_block(&self) -> Option<Arc<RecoveredBlock<N::Block>>> {
546        self.pending_state().map(|block_state| Arc::clone(&block_state.block_ref().recovered_block))
547    }
548
549    /// Returns the pending recovered block and its execution output, which contains the receipts.
550    pub fn pending_block_and_receipts(
551        &self,
552    ) -> Option<RecoveredBlockAndExecutionOutput<N::Block, N::Receipt>> {
553        self.pending_state().map(|block_state| {
554            RecoveredBlockAndExecutionOutput::new(
555                Arc::clone(&block_state.block_ref().recovered_block),
556                Arc::clone(&block_state.block_ref().execution_output),
557            )
558        })
559    }
560
561    /// Subscribe to new blocks events.
562    pub fn subscribe_canon_state(&self) -> CanonStateNotifications<N> {
563        self.inner.canon_state_notification_sender.subscribe()
564    }
565
566    /// Subscribe to new safe block events.
567    pub fn subscribe_safe_block(&self) -> watch::Receiver<Option<SealedHeader<N::BlockHeader>>> {
568        self.inner.chain_info_tracker.subscribe_safe_block()
569    }
570
571    /// Subscribe to new finalized block events.
572    pub fn subscribe_finalized_block(
573        &self,
574    ) -> watch::Receiver<Option<SealedHeader<N::BlockHeader>>> {
575        self.inner.chain_info_tracker.subscribe_finalized_block()
576    }
577
578    /// Subscribe to new persisted block events.
579    pub fn subscribe_persisted_block(&self) -> watch::Receiver<Option<BlockNumHash>> {
580        self.inner.chain_info_tracker.subscribe_persisted_block()
581    }
582
583    /// Attempts to send a new [`CanonStateNotification`] to all active Receiver handles.
584    pub fn notify_canon_state(&self, event: CanonStateNotification<N>) {
585        self.inner.canon_state_notification_sender.send(event).ok();
586    }
587
588    /// Returns an iterator over all __canonical blocks__ in the in-memory state, from newest to
589    /// oldest (highest to lowest).
590    ///
591    /// This iterator contains a snapshot of the in-memory state at the time of the call.
592    pub fn canonical_chain(&self) -> impl Iterator<Item = Arc<BlockState<N>>> {
593        self.inner.in_memory_state.head_state().into_iter().flat_map(|head| head.iter())
594    }
595
596    /// Returns [`SignedTransaction`] type for the given `TxHash` if found.
597    ///
598    /// [`SignedTransaction`]: reth_primitives_traits::SignedTransaction
599    pub fn transaction_by_hash(&self, hash: TxHash) -> Option<N::SignedTx> {
600        for block_state in self.canonical_chain() {
601            if let Some(tx) =
602                block_state.block_ref().recovered_block().body().transaction_by_hash(&hash)
603            {
604                return Some(tx.clone())
605            }
606        }
607        None
608    }
609
610    /// Returns a tuple with [`SignedTransaction`] type and [`TransactionMeta`] for the
611    /// given [`TxHash`] if found.
612    ///
613    /// [`SignedTransaction`]: reth_primitives_traits::SignedTransaction
614    pub fn transaction_by_hash_with_meta(
615        &self,
616        tx_hash: TxHash,
617    ) -> Option<(N::SignedTx, TransactionMeta)> {
618        for block_state in self.canonical_chain() {
619            if let Some(indexed) = block_state.find_indexed(tx_hash) {
620                return Some((indexed.tx().clone(), indexed.meta()));
621            }
622        }
623        None
624    }
625}
626
627/// Creates a [`CanonicalInMemoryState`] and changes it: the blocks it tracks, its chain info, and
628/// the notifications it sends.
629///
630/// A writer is created together with its state. [`Self::canonical_in_memory_state`] returns that
631/// state, which can be cloned and is what everything but the owner of the writer reads. What is
632/// written through the writer is read through the state and every clone of it.
633///
634/// A writer cannot be cloned and its methods take `&mut self`, so only its owner changes the
635/// state through it. The constructors of [`CanonicalInMemoryState`] and its methods that change
636/// it are still public.
637#[derive(Debug)]
638pub struct CanonicalInMemoryStateWriter<N: NodePrimitives = EthPrimitives> {
639    canonical_in_memory_state: CanonicalInMemoryState<N>,
640}
641
642impl<N: NodePrimitives> CanonicalInMemoryStateWriter<N> {
643    /// Creates a canonical state over the blocks of `in_memory_state`, with the canonical head
644    /// and the safe and finalized blocks of `chain_info_headers`, and returns its writer.
645    ///
646    /// The blocks are shared with every other handle of `in_memory_state`. The chain info and the
647    /// notifications belong to the created state and its clones.
648    pub fn new(
649        chain_info_headers: ChainInfoHeaders<N::BlockHeader>,
650        in_memory_state: InMemoryState<N>,
651    ) -> Self {
652        Self {
653            canonical_in_memory_state: CanonicalInMemoryState::with_head(
654                chain_info_headers,
655                in_memory_state,
656            ),
657        }
658    }
659
660    /// Returns the state this changes.
661    pub const fn canonical_in_memory_state(&self) -> &CanonicalInMemoryState<N> {
662        &self.canonical_in_memory_state
663    }
664
665    /// See [`CanonicalInMemoryState::clear_state`].
666    pub fn clear_state(&mut self) {
667        self.canonical_in_memory_state.clear_state();
668    }
669
670    /// See [`CanonicalInMemoryState::insert_executed`].
671    pub fn insert_executed(&mut self, block: ExecutedBlock<N>) {
672        self.canonical_in_memory_state.insert_executed(block);
673    }
674
675    /// See [`CanonicalInMemoryState::set_pending_block`].
676    pub fn set_pending_block(&mut self, pending: ExecutedBlock<N>) {
677        self.canonical_in_memory_state.set_pending_block(pending);
678    }
679
680    /// See [`CanonicalInMemoryState::update_chain`].
681    pub fn update_chain(&mut self, new_chain: NewCanonicalChain<N>) {
682        self.canonical_in_memory_state.update_chain(new_chain);
683    }
684
685    /// See [`CanonicalInMemoryState::on_backfill_finished`].
686    pub fn on_backfill_finished(
687        &mut self,
688        last_persisted_hash: B256,
689        backfill_block: BlockNumHash,
690    ) {
691        self.canonical_in_memory_state.on_backfill_finished(last_persisted_hash, backfill_block);
692    }
693
694    /// See [`CanonicalInMemoryState::on_blocks_persisted`].
695    pub fn on_blocks_persisted(
696        &mut self,
697        last_persisted_block: BlockNumHash,
698        state_trie_persisted_block: BlockNumHash,
699        finalized: Option<BlockNumHash>,
700    ) {
701        self.canonical_in_memory_state.on_blocks_persisted(
702            last_persisted_block,
703            state_trie_persisted_block,
704            finalized,
705        );
706    }
707
708    /// See [`CanonicalInMemoryState::on_forkchoice_update_received`].
709    pub fn on_forkchoice_update_received(&mut self) {
710        self.canonical_in_memory_state.on_forkchoice_update_received();
711    }
712
713    /// See [`CanonicalInMemoryState::set_canonical_head`].
714    pub fn set_canonical_head(&mut self, header: SealedHeader<N::BlockHeader>) {
715        self.canonical_in_memory_state.set_canonical_head(header);
716    }
717
718    /// See [`CanonicalInMemoryState::set_safe`].
719    pub fn set_safe(&mut self, header: SealedHeader<N::BlockHeader>) {
720        self.canonical_in_memory_state.set_safe(header);
721    }
722
723    /// See [`CanonicalInMemoryState::set_finalized`].
724    pub fn set_finalized(&mut self, header: SealedHeader<N::BlockHeader>) {
725        self.canonical_in_memory_state.set_finalized(header);
726    }
727
728    /// See [`CanonicalInMemoryState::notify_canon_state`].
729    pub fn notify_canon_state(&mut self, event: CanonStateNotification<N>) {
730        self.canonical_in_memory_state.notify_canon_state(event);
731    }
732}
733
734#[cfg(test)]
735mod tests {
736    use super::*;
737    use crate::test_utils::TestBlockBuilder;
738    use rand::Rng;
739
740    fn create_mock_state(
741        test_block_builder: &mut TestBlockBuilder<EthPrimitives>,
742        block_number: u64,
743        parent_hash: B256,
744    ) -> BlockState {
745        BlockState::new(
746            test_block_builder.get_executed_block_with_number(block_number, parent_hash),
747        )
748    }
749
750    #[test]
751    fn test_in_memory_state_impl_state_by_hash() {
752        let mut state_by_hash = B256Map::default();
753        let number = rand::rng().random::<u64>();
754        let mut test_block_builder: TestBlockBuilder = TestBlockBuilder::default();
755        let state = Arc::new(create_mock_state(&mut test_block_builder, number, B256::random()));
756        state_by_hash.insert(state.hash(), state.clone());
757
758        let in_memory_state = InMemoryState::new(state_by_hash, BTreeMap::new(), None);
759
760        assert_eq!(in_memory_state.state_by_hash(state.hash()), Some(state));
761        assert_eq!(in_memory_state.state_by_hash(B256::random()), None);
762    }
763
764    #[test]
765    fn test_in_memory_state_impl_state_by_number() {
766        let mut state_by_hash = B256Map::default();
767        let mut hash_by_number = BTreeMap::new();
768
769        let number = rand::rng().random::<u64>();
770        let mut test_block_builder: TestBlockBuilder = TestBlockBuilder::default();
771        let state = Arc::new(create_mock_state(&mut test_block_builder, number, B256::random()));
772        let hash = state.hash();
773
774        state_by_hash.insert(hash, state.clone());
775        hash_by_number.insert(number, hash);
776
777        let in_memory_state = InMemoryState::new(state_by_hash, hash_by_number, None);
778
779        assert_eq!(in_memory_state.state_by_number(number), Some(state));
780        assert_eq!(in_memory_state.state_by_number(number + 1), None);
781    }
782
783    #[test]
784    fn test_in_memory_state_impl_head_state() {
785        let mut state_by_hash = B256Map::default();
786        let mut hash_by_number = BTreeMap::new();
787        let mut test_block_builder: TestBlockBuilder = TestBlockBuilder::default();
788        let state1 = Arc::new(create_mock_state(&mut test_block_builder, 1, B256::random()));
789        let hash1 = state1.hash();
790        let state2 = Arc::new(create_mock_state(&mut test_block_builder, 2, hash1));
791        let hash2 = state2.hash();
792        hash_by_number.insert(1, hash1);
793        hash_by_number.insert(2, hash2);
794        state_by_hash.insert(hash1, state1);
795        state_by_hash.insert(hash2, state2);
796
797        let in_memory_state = InMemoryState::new(state_by_hash, hash_by_number, None);
798        let head_state = in_memory_state.head_state().unwrap();
799
800        assert_eq!(head_state.hash(), hash2);
801        assert_eq!(head_state.number(), 2);
802    }
803
804    #[test]
805    fn test_in_memory_state_impl_pending_state() {
806        let pending_number = rand::rng().random::<u64>();
807        let mut test_block_builder: TestBlockBuilder = TestBlockBuilder::default();
808        let pending_state =
809            create_mock_state(&mut test_block_builder, pending_number, B256::random());
810        let pending_hash = pending_state.hash();
811
812        let in_memory_state =
813            InMemoryState::new(B256Map::default(), BTreeMap::new(), Some(pending_state));
814
815        let result = in_memory_state.pending_state();
816        assert!(result.is_some());
817        let actual_pending_state = result.unwrap();
818        assert_eq!(actual_pending_state.block.recovered_block().hash(), pending_hash);
819        assert_eq!(actual_pending_state.block.recovered_block().number, pending_number);
820    }
821
822    #[test]
823    fn test_in_memory_state_impl_no_pending_state() {
824        let in_memory_state: InMemoryState =
825            InMemoryState::new(B256Map::default(), BTreeMap::new(), None);
826
827        assert_eq!(in_memory_state.pending_state(), None);
828    }
829
830    #[test]
831    fn test_in_memory_state_chain_update() {
832        let state: CanonicalInMemoryState = CanonicalInMemoryState::empty();
833        let mut test_block_builder: TestBlockBuilder = TestBlockBuilder::default();
834        let block1 = test_block_builder.get_executed_block_with_number(0, B256::random());
835        let block2 = test_block_builder.get_executed_block_with_number(0, B256::random());
836        let chain = NewCanonicalChain::Commit { new: vec![block1.clone()] };
837        state.update_chain(chain);
838        assert_eq!(
839            state.head_state().unwrap().block_ref().recovered_block().hash(),
840            block1.recovered_block().hash()
841        );
842        assert_eq!(
843            state.state_by_number(0).unwrap().block_ref().recovered_block().hash(),
844            block1.recovered_block().hash()
845        );
846
847        let chain = NewCanonicalChain::Reorg { new: vec![block2.clone()], old: vec![block1] };
848        state.update_chain(chain);
849        assert_eq!(
850            state.head_state().unwrap().block_ref().recovered_block().hash(),
851            block2.recovered_block().hash()
852        );
853        assert_eq!(
854            state.state_by_number(0).unwrap().block_ref().recovered_block().hash(),
855            block2.recovered_block().hash()
856        );
857
858        assert_eq!(state.inner.in_memory_state.block_count(), 1);
859    }
860
861    #[test]
862    fn test_in_memory_state_set_pending_block() {
863        let state: CanonicalInMemoryState = CanonicalInMemoryState::empty();
864        let mut test_block_builder: TestBlockBuilder = TestBlockBuilder::default();
865
866        // First random block
867        let block1 = test_block_builder.get_executed_block_with_number(0, B256::random());
868
869        // Second block with parent hash of the first block
870        let block2 =
871            test_block_builder.get_executed_block_with_number(1, block1.recovered_block().hash());
872
873        // Commit the two blocks
874        let chain = NewCanonicalChain::Commit { new: vec![block1.clone(), block2.clone()] };
875        state.update_chain(chain);
876
877        // Assert that the pending state is None before setting it
878        assert!(state.pending_state().is_none());
879
880        // Set the pending block
881        state.set_pending_block(block2.clone());
882
883        // Check the pending state
884        assert_eq!(
885            *state.pending_state().unwrap(),
886            BlockState::with_parent(block2.clone(), Some(Arc::new(BlockState::new(block1))))
887        );
888
889        // Check the pending block
890        assert_eq!(state.pending_block().unwrap(), block2.recovered_block().sealed_block().clone());
891
892        // Check the pending block number and hash
893        assert_eq!(
894            state.pending_block_num_hash().unwrap(),
895            BlockNumHash { number: 1, hash: block2.recovered_block().hash() }
896        );
897
898        // Check the pending header
899        assert_eq!(state.pending_header().unwrap(), block2.recovered_block().header().clone());
900
901        // Check the pending sealed header
902        assert_eq!(
903            state.pending_sealed_header().unwrap(),
904            block2.recovered_block().clone_sealed_header()
905        );
906
907        // Check the pending block with senders
908        let pending_block = state.pending_recovered_block().unwrap();
909        assert!(Arc::ptr_eq(&pending_block, &block2.recovered_block));
910
911        // Check the pending block and receipts
912        let pending = state.pending_block_and_receipts().unwrap();
913        assert!(Arc::ptr_eq(pending.block(), &block2.recovered_block));
914        assert!(Arc::ptr_eq(pending.execution_output(), &block2.execution_output));
915    }
916
917    #[test]
918    fn test_in_memory_state_executed_blocks_are_not_canonical() {
919        let state: CanonicalInMemoryState = CanonicalInMemoryState::empty();
920        let mut test_block_builder: TestBlockBuilder = TestBlockBuilder::default();
921        let block1 = test_block_builder.get_executed_block_with_number(1, B256::random());
922        let block1_hash = block1.recovered_block().hash();
923        let block2 = test_block_builder.get_executed_block_with_number(2, block1_hash);
924        let block2_hash = block2.recovered_block().hash();
925        let fork2 = test_block_builder.get_executed_block_with_number(2, block1_hash);
926        let fork2_hash = fork2.recovered_block().hash();
927        let tracked = |hash| state.inner.in_memory_state.inner.blocks.read().contains(&hash);
928
929        // Executed blocks are tracked, but not canonical.
930        state.insert_executed(block1.clone());
931        state.insert_executed(block2.clone());
932        state.insert_executed(fork2.clone());
933        assert!(tracked(block1_hash) && tracked(block2_hash) && tracked(fork2_hash));
934        assert!(state.state_by_hash(block2_hash).is_none());
935        assert!(state.head_state().is_none());
936        assert!(state.pending_state().is_none());
937
938        // A chain update makes them canonical.
939        state.update_chain(NewCanonicalChain::Commit { new: vec![block1, block2.clone()] });
940        assert_eq!(state.head_state().unwrap().hash(), block2_hash);
941        assert!(state.state_by_hash(fork2_hash).is_none());
942
943        // A reorg keeps the replaced block tracked.
944        state.update_chain(NewCanonicalChain::Reorg { new: vec![fork2], old: vec![block2] });
945        assert_eq!(state.head_state().unwrap().hash(), fork2_hash);
946        assert!(state.state_by_hash(block2_hash).is_none());
947        assert!(tracked(block2_hash));
948
949        // The replaced block conflicts with the block that replaced it once that is finalized.
950        state.prune_conflicting_with_finalized(BlockNumHash::new(2, fork2_hash));
951        assert!(!tracked(block2_hash));
952        assert_eq!(state.inner.in_memory_state.block_count(), 2);
953    }
954
955    #[test]
956    fn test_canonical_in_memory_state_canonical_chain_empty() {
957        let state: CanonicalInMemoryState = CanonicalInMemoryState::empty();
958        assert!(state.canonical_chain().next().is_none());
959    }
960
961    #[test]
962    fn test_canonical_in_memory_state_canonical_chain_single_block() {
963        let block = TestBlockBuilder::eth().get_executed_block_with_number(1, B256::random());
964        let hash = block.recovered_block().hash();
965        let mut blocks = B256Map::default();
966        blocks.insert(hash, Arc::new(BlockState::new(block)));
967        let mut numbers = BTreeMap::new();
968        numbers.insert(1, hash);
969
970        let state = CanonicalInMemoryState::new(blocks, numbers, None, None, None);
971        let chain: Vec<_> = state.canonical_chain().collect();
972
973        assert_eq!(chain.len(), 1);
974        assert_eq!(chain[0].number(), 1);
975        assert_eq!(chain[0].hash(), hash);
976    }
977
978    #[test]
979    fn test_canonical_in_memory_state_canonical_chain_multiple_blocks() {
980        let mut parent_hash = B256::random();
981        let mut block_builder = TestBlockBuilder::eth();
982        let state: CanonicalInMemoryState = CanonicalInMemoryState::empty();
983
984        for i in 1..=3 {
985            let block = block_builder.get_executed_block_with_number(i, parent_hash);
986            let hash = block.recovered_block().hash();
987            state.update_chain(NewCanonicalChain::Commit { new: vec![block] });
988            parent_hash = hash;
989        }
990
991        let chain: Vec<_> = state.canonical_chain().collect();
992
993        assert_eq!(chain.len(), 3);
994        assert_eq!(chain[0].number(), 3);
995        assert_eq!(chain[1].number(), 2);
996        assert_eq!(chain[2].number(), 1);
997    }
998
999    // ensures the pending block is not part of the canonical chain
1000    #[test]
1001    fn test_canonical_in_memory_state_canonical_chain_with_pending_block() {
1002        let mut parent_hash = B256::random();
1003        let mut block_builder = TestBlockBuilder::<EthPrimitives>::eth();
1004        let state: CanonicalInMemoryState = CanonicalInMemoryState::empty();
1005
1006        for i in 1..=2 {
1007            let block = block_builder.get_executed_block_with_number(i, parent_hash);
1008            let hash = block.recovered_block().hash();
1009            state.update_chain(NewCanonicalChain::Commit { new: vec![block] });
1010            parent_hash = hash;
1011        }
1012
1013        let pending_block = block_builder.get_executed_block_with_number(3, parent_hash);
1014        state.set_pending_block(pending_block);
1015        let chain: Vec<_> = state.canonical_chain().collect();
1016
1017        assert_eq!(chain.len(), 2);
1018        assert_eq!(chain[0].number(), 2);
1019        assert_eq!(chain[1].number(), 1);
1020    }
1021
1022    #[test]
1023    fn test_canonical_in_memory_state_remove_persisted_blocks() {
1024        let state: CanonicalInMemoryState = CanonicalInMemoryState::empty();
1025        let blocks = TestBlockBuilder::eth().get_executed_blocks(1..6).collect::<Vec<_>>();
1026        let num_hash = |number: usize| blocks[number - 1].recovered_block().num_hash();
1027        // The numbers of the blocks a state is linked to, itself included.
1028        let chain = |state: &BlockState| state.chain().map(BlockState::number).collect::<Vec<_>>();
1029
1030        state.update_chain(NewCanonicalChain::Commit { new: blocks[..4].to_vec() });
1031        state.set_pending_block(blocks[4].clone());
1032
1033        // A persisted block that is not tracked is recorded, but removes nothing.
1034        let untracked = BlockNumHash::new(2, B256::random());
1035        state.remove_persisted_blocks(untracked);
1036        assert_eq!(state.get_persisted_num_hash(), Some(untracked));
1037        assert_eq!(chain(&state.head_state().unwrap()), [4, 3, 2, 1]);
1038        assert_eq!(chain(&state.pending_state().unwrap()), [5, 4, 3, 2, 1]);
1039
1040        // Only the blocks through the given number are removed. The blocks that stay and the
1041        // pending block are no longer linked to the removed ones.
1042        state.remove_persisted_blocks_until(num_hash(2), 1);
1043        assert_eq!(state.get_persisted_num_hash(), Some(num_hash(2)));
1044        assert_eq!(state.hash_by_number(1), None);
1045        assert_eq!(state.state_by_hash(num_hash(1).hash), None);
1046        assert_eq!(chain(&state.state_by_number(2).unwrap()), [2]);
1047        assert_eq!(chain(&state.head_state().unwrap()), [4, 3, 2]);
1048        assert_eq!(chain(&state.pending_state().unwrap()), [5, 4, 3, 2]);
1049
1050        // No block above the persisted block is removed.
1051        state.remove_persisted_blocks_until(num_hash(3), 4);
1052        assert_eq!(state.hash_by_number(3), None);
1053        assert_eq!(chain(&state.head_state().unwrap()), [4]);
1054        assert_eq!(chain(&state.pending_state().unwrap()), [5, 4]);
1055
1056        // The pending block stays when the last canonical block is removed.
1057        state.remove_persisted_blocks(num_hash(4));
1058        assert_eq!(state.head_state(), None);
1059        assert_eq!(state.inner.in_memory_state.block_count(), 0);
1060        assert_eq!(chain(&state.pending_state().unwrap()), [5]);
1061
1062        state.clear_state();
1063        assert_eq!(state.pending_state(), None);
1064    }
1065
1066    #[test]
1067    fn test_in_memory_state_removal_generation() {
1068        let state: CanonicalInMemoryState = CanonicalInMemoryState::empty();
1069        let in_memory_state = &state.inner.in_memory_state;
1070        let mut block_builder = TestBlockBuilder::eth();
1071        let blocks = block_builder.get_executed_blocks(1..4).collect::<Vec<_>>();
1072        let hash = |number: usize| blocks[number - 1].recovered_block().hash();
1073        let fork = block_builder.get_executed_block_with_number(2, hash(1));
1074        let fork_hash = fork.recovered_block().hash();
1075
1076        // Tracking blocks and making them canonical removes nothing.
1077        let generation = in_memory_state.removal_generation();
1078        state.update_chain(NewCanonicalChain::Commit { new: blocks.clone() });
1079        state.insert_executed(fork);
1080        assert_eq!(in_memory_state.removal_generation(), generation);
1081
1082        // The in-memory state returns a tracked block of either section, the canonical state
1083        // only a canonical one.
1084        assert_eq!(in_memory_state.state_by_hash(fork_hash).unwrap().hash(), fork_hash);
1085        assert_eq!(in_memory_state.state_by_hash(hash(3)).unwrap().hash(), hash(3));
1086        assert_eq!(state.state_by_hash(fork_hash), None);
1087
1088        // Nothing is removed for a block that is not on the canonical chain.
1089        state.remove_canonical_until(fork_hash, 3);
1090        assert_eq!(in_memory_state.removal_generation(), generation);
1091        assert_eq!(state.canonical_chain().count(), 3);
1092
1093        // Canonical blocks are removed for a canonical block.
1094        state.remove_canonical_until(hash(2), 1);
1095        let after_canonical_block = in_memory_state.removal_generation();
1096        assert!(after_canonical_block > generation);
1097        assert_eq!(in_memory_state.state_by_hash(hash(1)), None);
1098
1099        // They are also removed for the block the canonical chain builds on.
1100        state.remove_canonical_until(hash(1), 2);
1101        let after_chain_base = in_memory_state.removal_generation();
1102        assert!(after_chain_base > after_canonical_block);
1103        assert_eq!(state.canonical_chain().map(|state| state.number()).collect::<Vec<_>>(), [3]);
1104
1105        // Removing blocks that are not canonical counts as well.
1106        state.prune_conflicting_with_finalized(blocks[2].recovered_block().num_hash());
1107        let after_fork = in_memory_state.removal_generation();
1108        assert!(after_fork > after_chain_base);
1109        assert_eq!(in_memory_state.state_by_hash(fork_hash), None);
1110
1111        state.clear_state();
1112        assert!(in_memory_state.removal_generation() > after_fork);
1113        assert_eq!(in_memory_state.state_by_hash(hash(3)), None);
1114    }
1115
1116    #[test]
1117    fn test_on_backfill_finished_is_one_update() {
1118        let state: CanonicalInMemoryState = CanonicalInMemoryState::empty();
1119        let in_memory_state = &state.inner.in_memory_state;
1120        let mut block_builder = TestBlockBuilder::eth();
1121        let blocks = block_builder.get_executed_blocks(1..4).collect::<Vec<_>>();
1122        let hash = |number: usize| blocks[number - 1].recovered_block().hash();
1123        let fork = block_builder.get_executed_block_with_number(2, hash(1));
1124        let fork_hash = fork.recovered_block().hash();
1125        state.update_chain(NewCanonicalChain::Commit { new: blocks.clone() });
1126        state.insert_executed(fork);
1127
1128        // Backfill finishes at block 2: the canonical blocks through it and the fork are removed
1129        // in one update, and block 3 stays tracked but is no longer canonical.
1130        let generation = in_memory_state.removal_generation();
1131        state.on_backfill_finished(hash(1), blocks[1].recovered_block().num_hash());
1132        assert_eq!(in_memory_state.removal_generation(), generation + 1);
1133        assert_eq!(state.canonical_chain().count(), 0);
1134        for removed in [hash(1), hash(2), fork_hash] {
1135            assert_eq!(in_memory_state.state_by_hash(removed), None);
1136        }
1137        assert_eq!(in_memory_state.state_by_hash(hash(3)).unwrap().hash(), hash(3));
1138    }
1139
1140    #[test]
1141    fn test_on_backfill_finished_at_conflicting_block() {
1142        let state: CanonicalInMemoryState = CanonicalInMemoryState::empty();
1143        let in_memory_state = &state.inner.in_memory_state;
1144        let mut block_builder = TestBlockBuilder::eth();
1145        let blocks = block_builder.get_executed_blocks(1..4).collect::<Vec<_>>();
1146        let hash = |number: usize| blocks[number - 1].recovered_block().hash();
1147        let fork = block_builder.get_executed_block_with_number(2, hash(1));
1148        let fork_hash = fork.recovered_block().hash();
1149        let fork_child = block_builder.get_executed_block_with_number(3, fork_hash);
1150        let fork_child_hash = fork_child.recovered_block().hash();
1151        state.update_chain(NewCanonicalChain::Commit { new: blocks.clone() });
1152        state.insert_executed(fork.clone());
1153        state.insert_executed(fork_child);
1154
1155        // Backfill finishes at the fork block of height 2: canonical block 2 conflicts with it
1156        // and is removed together with block 3 built on it, and the fork stays tracked.
1157        let generation = in_memory_state.removal_generation();
1158        state.on_backfill_finished(hash(1), fork.recovered_block().num_hash());
1159        assert_eq!(in_memory_state.removal_generation(), generation + 1);
1160        assert_eq!(state.canonical_chain().count(), 0);
1161        for removed in [hash(1), hash(2), hash(3)] {
1162            assert_eq!(in_memory_state.state_by_hash(removed), None);
1163        }
1164        for kept in [fork_hash, fork_child_hash] {
1165            assert_eq!(in_memory_state.state_by_hash(kept).unwrap().hash(), kept);
1166        }
1167    }
1168
1169    #[test]
1170    fn test_on_blocks_persisted() {
1171        let state: CanonicalInMemoryState = CanonicalInMemoryState::empty();
1172        let in_memory_state = &state.inner.in_memory_state;
1173        let mut block_builder = TestBlockBuilder::eth();
1174        let blocks = block_builder.get_executed_blocks(1..6).collect::<Vec<_>>();
1175        let hash = |number: usize| blocks[number - 1].recovered_block().hash();
1176        let num_hash = |number: usize| blocks[number - 1].recovered_block().num_hash();
1177        // One fork at the height of each of the blocks 2, 3 and 4.
1178        let forks = (2..5)
1179            .map(|number| {
1180                block_builder.get_executed_block_with_number(number as u64, hash(number - 1))
1181            })
1182            .collect::<Vec<_>>();
1183        let fork_hash = |number: usize| forks[number - 2].recovered_block().hash();
1184        state.update_chain(NewCanonicalChain::Commit { new: blocks.clone() });
1185        for fork in &forks {
1186            state.insert_executed(fork.clone());
1187        }
1188
1189        // Without a finalized block only the canonical blocks up to the state trie frontier are
1190        // removed, in one update.
1191        let generation = in_memory_state.removal_generation();
1192        state.on_blocks_persisted(num_hash(2), num_hash(1), None);
1193        assert_eq!(in_memory_state.removal_generation(), generation + 1);
1194        assert_eq!(state.get_persisted_num_hash(), Some(num_hash(2)));
1195        assert_eq!(
1196            in_memory_state.block_counts(),
1197            InMemoryStateBlockCounts { canonical: 4, non_canonical: 3 }
1198        );
1199        assert!(!in_memory_state.contains(&hash(1)));
1200
1201        // A finalized block above the state trie frontier is replaced by the frontier: the fork
1202        // at the height of block 2 conflicts with it, the ones above do not.
1203        state.on_blocks_persisted(num_hash(2), num_hash(2), Some(num_hash(4)));
1204        assert_eq!(in_memory_state.removal_generation(), generation + 2);
1205        assert_eq!(
1206            in_memory_state.block_counts(),
1207            InMemoryStateBlockCounts { canonical: 3, non_canonical: 2 }
1208        );
1209        assert!(!in_memory_state.contains(&fork_hash(2)));
1210
1211        // A finalized block below the frontier is used as it is.
1212        state.on_blocks_persisted(num_hash(4), num_hash(4), Some(num_hash(3)));
1213        assert_eq!(
1214            in_memory_state.block_counts(),
1215            InMemoryStateBlockCounts { canonical: 1, non_canonical: 1 }
1216        );
1217        assert!(!in_memory_state.contains(&fork_hash(3)));
1218        assert!(in_memory_state.contains(&fork_hash(4)));
1219    }
1220
1221    #[test]
1222    fn test_on_blocks_persisted_after_disk_removal() {
1223        let state: CanonicalInMemoryState = CanonicalInMemoryState::empty();
1224        let in_memory_state = &state.inner.in_memory_state;
1225        let mut block_builder = TestBlockBuilder::eth();
1226        let blocks = block_builder.get_executed_blocks(1..9).collect::<Vec<_>>();
1227        let hash = |number: usize| blocks[number - 1].recovered_block().hash();
1228        let num_hash = |number: usize| blocks[number - 1].recovered_block().num_hash();
1229        let fork = block_builder.get_executed_block_with_number(7, hash(6));
1230        let fork_hash = fork.recovered_block().hash();
1231        let fork_child = block_builder.get_executed_block_with_number(8, fork_hash);
1232
1233        // Block 8 is loaded from disk as the canonical head, and replaced by block 6 before its
1234        // parent is loaded: it is tracked, but block 7 is only on disk.
1235        state.update_chain(NewCanonicalChain::Commit { new: vec![blocks[7].clone()] });
1236        state.update_chain(NewCanonicalChain::Reorg {
1237            new: vec![blocks[5].clone()],
1238            old: vec![blocks[7].clone()],
1239        });
1240        state.insert_executed(fork);
1241        state.insert_executed(fork_child.clone());
1242        assert_eq!(
1243            in_memory_state.block_counts(),
1244            InMemoryStateBlockCounts { canonical: 1, non_canonical: 3 }
1245        );
1246
1247        // The blocks above block 6 are removed from disk. Block 8 builds on block 7, which is
1248        // gone, so it is removed. The fork builds on block 6 and stays.
1249        state.on_blocks_persisted(num_hash(6), num_hash(6), None);
1250        assert!(!in_memory_state.contains(&hash(8)));
1251        assert_eq!(
1252            in_memory_state.block_counts(),
1253            InMemoryStateBlockCounts { canonical: 0, non_canonical: 2 }
1254        );
1255        assert_eq!(
1256            in_memory_state.state_by_hash(fork_child.recovered_block().hash()).unwrap().anchor(),
1257            num_hash(6)
1258        );
1259    }
1260
1261    #[test]
1262    fn test_in_memory_state_contains_and_block_counts() {
1263        let state: CanonicalInMemoryState = CanonicalInMemoryState::empty();
1264        let in_memory_state = &state.inner.in_memory_state;
1265        let mut block_builder = TestBlockBuilder::eth();
1266        let blocks = block_builder.get_executed_blocks(1..3).collect::<Vec<_>>();
1267        let fork =
1268            block_builder.get_executed_block_with_number(2, blocks[0].recovered_block().hash());
1269        state.update_chain(NewCanonicalChain::Commit { new: blocks.clone() });
1270        state.insert_executed(fork.clone());
1271
1272        assert_eq!(
1273            in_memory_state.block_counts(),
1274            InMemoryStateBlockCounts { canonical: 2, non_canonical: 1 }
1275        );
1276        for block in blocks.iter().chain([&fork]) {
1277            assert!(in_memory_state.contains(&block.recovered_block().hash()));
1278        }
1279        assert!(!in_memory_state.contains(&B256::random()));
1280    }
1281
1282    #[test]
1283    fn test_writer_changes_blocks_of_canonical_state() {
1284        let mut writer = CanonicalInMemoryStateWriter::new(
1285            ChainInfoHeaders {
1286                canonical_head: SealedHeader::default(),
1287                safe: None,
1288                finalized: None,
1289            },
1290            InMemoryState::default(),
1291        );
1292        let state: CanonicalInMemoryState = writer.canonical_in_memory_state().clone();
1293        let mut block_builder = TestBlockBuilder::eth();
1294        let blocks = block_builder.get_executed_blocks(1..4).collect::<Vec<_>>();
1295        let hash = |number: usize| blocks[number - 1].recovered_block().hash();
1296        let num_hash = |number: usize| blocks[number - 1].recovered_block().num_hash();
1297        let fork = block_builder.get_executed_block_with_number(2, hash(1));
1298        let fork_hash = fork.recovered_block().hash();
1299        let in_memory_state = &state.inner.in_memory_state;
1300
1301        // Blocks written through the writer are read through the state it was created for.
1302        writer.insert_executed(blocks[0].clone());
1303        writer.set_pending_block(blocks[1].clone());
1304        assert_eq!(state.pending_block_num_hash(), Some(num_hash(2)));
1305        writer.update_chain(NewCanonicalChain::Commit { new: blocks[..2].to_vec() });
1306        writer.insert_executed(blocks[2].clone());
1307        writer.insert_executed(fork);
1308        assert_eq!(state.canonical_chain().count(), 2);
1309        assert_eq!(
1310            in_memory_state.block_counts(),
1311            InMemoryStateBlockCounts { canonical: 2, non_canonical: 2 }
1312        );
1313
1314        // Persisting the blocks 1 and 2 removes them, and finalizing block 2 removes the fork at
1315        // its height.
1316        writer.on_blocks_persisted(num_hash(2), num_hash(2), Some(num_hash(2)));
1317        assert_eq!(state.get_persisted_num_hash(), Some(num_hash(2)));
1318        for removed in [hash(1), hash(2), fork_hash] {
1319            assert!(!in_memory_state.contains(&removed));
1320        }
1321
1322        // After a backfill run that ends at block 2, block 3 is no longer canonical.
1323        writer.update_chain(NewCanonicalChain::Commit { new: vec![blocks[2].clone()] });
1324        assert_eq!(state.canonical_chain().count(), 1);
1325        writer.on_backfill_finished(hash(2), num_hash(2));
1326        assert_eq!(
1327            in_memory_state.block_counts(),
1328            InMemoryStateBlockCounts { canonical: 0, non_canonical: 1 }
1329        );
1330
1331        writer.clear_state();
1332        assert_eq!(
1333            in_memory_state.block_counts(),
1334            InMemoryStateBlockCounts { canonical: 0, non_canonical: 0 }
1335        );
1336
1337        // The chain info set through the writer is read through the state as well.
1338        let header = blocks[2].recovered_block().clone_sealed_header();
1339        writer.on_forkchoice_update_received();
1340        writer.set_canonical_head(header.clone());
1341        writer.set_safe(header.clone());
1342        writer.set_finalized(header.clone());
1343        assert!(state.last_received_update_timestamp().is_some());
1344        assert_eq!(state.get_canonical_head(), header);
1345        assert_eq!(state.get_safe_num_hash(), Some(header.num_hash()));
1346        assert_eq!(state.get_finalized_num_hash(), Some(header.num_hash()));
1347    }
1348}