reth_storage_api/
trie.rs

1use alloc::vec::Vec;
2use alloy_primitives::{Address, BlockNumber, Bytes, B256};
3use reth_storage_errors::provider::ProviderResult;
4use reth_trie_common::{
5    updates::{StorageTrieUpdatesSorted, TrieUpdates, TrieUpdatesSorted},
6    AccountProof, HashedPostState, HashedStorage, MultiProof, MultiProofTargets, StorageMultiProof,
7    StorageProof, TrieInput,
8};
9
10/// A type that can compute the state root of a given post state.
11#[auto_impl::auto_impl(&, Box, Arc)]
12pub trait StateRootProvider: Send + Sync {
13    /// Returns the state root of the `BundleState` on top of the current state.
14    ///
15    /// # Note
16    ///
17    /// It is recommended to provide a different implementation from
18    /// `state_root_with_updates` since it affects the memory usage during state root
19    /// computation.
20    fn state_root(&self, hashed_state: HashedPostState) -> ProviderResult<B256>;
21
22    /// Returns the state root of the `HashedPostState` on top of the current state but reuses the
23    /// intermediate nodes to speed up the computation. It's up to the caller to construct the
24    /// prefix sets and inform the provider of the trie paths that have changes.
25    fn state_root_from_nodes(&self, input: TrieInput) -> ProviderResult<B256>;
26
27    /// Returns the state root of the `HashedPostState` on top of the current state with trie
28    /// updates to be committed to the database.
29    fn state_root_with_updates(
30        &self,
31        hashed_state: HashedPostState,
32    ) -> ProviderResult<(B256, TrieUpdates)>;
33
34    /// Returns state root and trie updates.
35    /// See [`StateRootProvider::state_root_from_nodes`] for more info.
36    fn state_root_from_nodes_with_updates(
37        &self,
38        input: TrieInput,
39    ) -> ProviderResult<(B256, TrieUpdates)>;
40}
41
42/// A type that can compute the storage root for a given account.
43#[auto_impl::auto_impl(&, Box, Arc)]
44pub trait StorageRootProvider: Send + Sync {
45    /// Returns the storage root of the `HashedStorage` for target address on top of the current
46    /// state.
47    fn storage_root(&self, address: Address, hashed_storage: HashedStorage)
48        -> ProviderResult<B256>;
49
50    /// Returns the storage proof of the `HashedStorage` for target slot on top of the current
51    /// state.
52    fn storage_proof(
53        &self,
54        address: Address,
55        slot: B256,
56        hashed_storage: HashedStorage,
57    ) -> ProviderResult<StorageProof>;
58
59    /// Returns the storage multiproof for target slots.
60    fn storage_multiproof(
61        &self,
62        address: Address,
63        slots: &[B256],
64        hashed_storage: HashedStorage,
65    ) -> ProviderResult<StorageMultiProof>;
66}
67
68/// A type that can generate state proof on top of a given post state.
69#[auto_impl::auto_impl(&, Box, Arc)]
70pub trait StateProofProvider: Send + Sync {
71    /// Get account and storage proofs of target keys in the `HashedPostState`
72    /// on top of the current state.
73    fn proof(
74        &self,
75        input: TrieInput,
76        address: Address,
77        slots: &[B256],
78    ) -> ProviderResult<AccountProof>;
79
80    /// Generate [`MultiProof`] for target hashed account and corresponding
81    /// hashed storage slot keys.
82    fn multiproof(
83        &self,
84        input: TrieInput,
85        targets: MultiProofTargets,
86    ) -> ProviderResult<MultiProof>;
87
88    /// Get trie witness for provided state.
89    fn witness(&self, input: TrieInput, target: HashedPostState) -> ProviderResult<Vec<Bytes>>;
90}
91
92/// Trie Reader
93#[auto_impl::auto_impl(&, Arc, Box)]
94pub trait TrieReader: Send + Sync {
95    /// Returns the [`TrieUpdatesSorted`] for reverting the trie database to its state prior to the
96    /// given block and onwards having been processed.
97    fn trie_reverts(&self, from: BlockNumber) -> ProviderResult<TrieUpdatesSorted>;
98
99    /// Returns the trie updates that were applied by the specified block.
100    fn get_block_trie_updates(
101        &self,
102        block_number: BlockNumber,
103    ) -> ProviderResult<TrieUpdatesSorted>;
104}
105
106/// Trie Writer
107#[auto_impl::auto_impl(&, Arc, Box)]
108pub trait TrieWriter: Send + Sync {
109    /// Writes trie updates to the database.
110    ///
111    /// Returns the number of entries modified.
112    fn write_trie_updates(&self, trie_updates: TrieUpdates) -> ProviderResult<usize> {
113        self.write_trie_updates_sorted(&trie_updates.into_sorted())
114    }
115
116    /// Writes trie updates to the database with already sorted updates.
117    ///
118    /// Returns the number of entries modified.
119    fn write_trie_updates_sorted(&self, trie_updates: &TrieUpdatesSorted) -> ProviderResult<usize>;
120
121    /// Records the current values of all trie nodes which will be updated using the [`TrieUpdates`]
122    /// into the trie changesets tables.
123    ///
124    /// The intended usage of this method is to call it _prior_ to calling `write_trie_updates` with
125    /// the same [`TrieUpdates`].
126    ///
127    /// The `updates_overlay` parameter allows providing additional in-memory trie updates that
128    /// should be considered when looking up current node values. When provided, these overlay
129    /// updates are applied on top of the database state, allowing the method to see a view that
130    /// includes both committed database values and pending in-memory changes. This is useful
131    /// when writing changesets for updates that depend on previous uncommitted trie changes.
132    ///
133    /// Returns the number of keys written.
134    fn write_trie_changesets(
135        &self,
136        block_number: BlockNumber,
137        trie_updates: &TrieUpdatesSorted,
138        updates_overlay: Option<&TrieUpdatesSorted>,
139    ) -> ProviderResult<usize>;
140
141    /// Clears contents of trie changesets completely
142    fn clear_trie_changesets(&self) -> ProviderResult<()>;
143
144    /// Clears contents of trie changesets starting from the given block number (inclusive) onwards.
145    fn clear_trie_changesets_from(&self, from: BlockNumber) -> ProviderResult<()>;
146}
147
148/// Storage Trie Writer
149#[auto_impl::auto_impl(&, Arc, Box)]
150pub trait StorageTrieWriter: Send + Sync {
151    /// Writes storage trie updates from the given storage trie map with already sorted updates.
152    ///
153    /// Expects the storage trie updates to already be sorted by the hashed address key.
154    ///
155    /// Returns the number of entries modified.
156    fn write_storage_trie_updates_sorted<'a>(
157        &self,
158        storage_tries: impl Iterator<Item = (&'a B256, &'a StorageTrieUpdatesSorted)>,
159    ) -> ProviderResult<usize>;
160
161    /// Records the current values of all trie nodes which will be updated using the
162    /// [`StorageTrieUpdatesSorted`] into the storage trie changesets table.
163    ///
164    /// The intended usage of this method is to call it _prior_ to calling
165    /// `write_storage_trie_updates` with the same set of [`StorageTrieUpdatesSorted`].
166    ///
167    /// The `updates_overlay` parameter allows providing additional in-memory trie updates that
168    /// should be considered when looking up current node values. When provided, these overlay
169    /// updates are applied on top of the database state for each storage trie, allowing the
170    /// method to see a view that includes both committed database values and pending in-memory
171    /// changes. This is useful when writing changesets for storage updates that depend on
172    /// previous uncommitted trie changes.
173    ///
174    /// Returns the number of keys written.
175    fn write_storage_trie_changesets<'a>(
176        &self,
177        block_number: BlockNumber,
178        storage_tries: impl Iterator<Item = (&'a B256, &'a StorageTrieUpdatesSorted)>,
179        updates_overlay: Option<&TrieUpdatesSorted>,
180    ) -> ProviderResult<usize>;
181}
reth_storage_api/trie.rs

reth_storage_api/
trie.rs
