reth_transaction_pool/blobstore/
mod.rs

1//! Storage for blob data of EIP4844 transactions.
2
3use alloy_eips::{
4    eip4844::{BlobAndProofV1, BlobAndProofV2, BlobCellsAndProofsV1},
5    eip7594::{BlobTransactionSidecarVariant, Cell},
6};
7use alloy_primitives::{TxHash, B128, B256};
8pub use converter::BlobSidecarConverter;
9pub use disk::{DiskFileBlobStore, DiskFileBlobStoreConfig, OpenDiskFileBlobStore};
10pub use mem::InMemoryBlobStore;
11pub use noop::NoopBlobStore;
12use std::{
13    fmt,
14    sync::{
15        atomic::{AtomicUsize, Ordering},
16        Arc,
17    },
18};
19pub use tracker::{BlobStoreCanonTracker, BlobStoreUpdates};
20
21mod converter;
22pub mod disk;
23mod mem;
24mod noop;
25mod tracker;
26
27/// A blob store that can be used to store blob data of EIP4844 transactions.
28///
29/// This type is responsible for keeping track of blob data until it is no longer needed (after
30/// finalization).
31///
32/// Note: this is Clone because it is expected to be wrapped in an Arc.
33pub trait BlobStore: fmt::Debug + Send + Sync + 'static {
34    /// Inserts the blob sidecar into the store
35    fn insert(&self, tx: B256, data: BlobTransactionSidecarVariant) -> Result<(), BlobStoreError>;
36
37    /// Inserts multiple blob sidecars into the store
38    fn insert_all(
39        &self,
40        txs: Vec<(B256, BlobTransactionSidecarVariant)>,
41    ) -> Result<(), BlobStoreError>;
42
43    /// Deletes the blob sidecar from the store
44    fn delete(&self, tx: B256) -> Result<(), BlobStoreError>;
45
46    /// Deletes multiple blob sidecars from the store
47    fn delete_all(&self, txs: Vec<B256>) -> Result<(), BlobStoreError>;
48
49    /// A maintenance function that can be called periodically to clean up the blob store, returns
50    /// the number of successfully deleted blobs and the number of failed deletions.
51    ///
52    /// This is intended to be called in the background to clean up any old or unused data, in case
53    /// the store uses deferred cleanup: [`DiskFileBlobStore`]
54    fn cleanup(&self) -> BlobStoreCleanupStat;
55
56    /// Retrieves the decoded blob data for the given transaction hash.
57    fn get(&self, tx: B256) -> Result<Option<Arc<BlobTransactionSidecarVariant>>, BlobStoreError>;
58
59    /// Checks if the given transaction hash is in the blob store.
60    fn contains(&self, tx: B256) -> Result<bool, BlobStoreError>;
61
62    /// Retrieves all decoded blob data for the given transaction hashes.
63    ///
64    /// This only returns the blobs that were found in the store.
65    /// If there's no blob it will not be returned.
66    ///
67    /// Note: this is not guaranteed to return the blobs in the same order as the input.
68    fn get_all(
69        &self,
70        txs: Vec<B256>,
71    ) -> Result<Vec<(B256, Arc<BlobTransactionSidecarVariant>)>, BlobStoreError>;
72
73    /// Returns the exact [`BlobTransactionSidecarVariant`] for the given transaction hashes in the
74    /// exact order they were requested.
75    ///
76    /// Returns an error if any of the blobs are not found in the blob store.
77    fn get_exact(
78        &self,
79        txs: Vec<B256>,
80    ) -> Result<Vec<Arc<BlobTransactionSidecarVariant>>, BlobStoreError>;
81
82    /// Return the [`BlobAndProofV1`]s for a list of blob versioned hashes.
83    fn get_by_versioned_hashes_v1(
84        &self,
85        versioned_hashes: &[B256],
86    ) -> Result<Vec<Option<BlobAndProofV1>>, BlobStoreError>;
87
88    /// Return the [`BlobAndProofV2`]s for a list of blob versioned hashes.
89    /// Blobs and proofs are returned only if they are present for _all_ requested
90    /// versioned hashes.
91    ///
92    /// This differs from [`BlobStore::get_by_versioned_hashes_v1`] in that it also returns all the
93    /// cell proofs in [`BlobAndProofV2`] supported by the EIP-7594 blob sidecar variant.
94    ///
95    /// The response also differs from [`BlobStore::get_by_versioned_hashes_v1`] in that this
96    /// returns `None` if any of the requested versioned hashes are not present in the blob store:
97    /// e.g. where v1 would return `[A, None, C]` v2 would return `None`. See also <https://github.com/ethereum/execution-apis/blob/main/src/engine/osaka.md#engine_getblobsv2>
98    fn get_by_versioned_hashes_v2(
99        &self,
100        versioned_hashes: &[B256],
101    ) -> Result<Option<Vec<BlobAndProofV2>>, BlobStoreError>;
102
103    /// Return the [`BlobAndProofV2`]s for a list of blob versioned hashes.
104    ///
105    /// The response is always the same length as the request. Missing or older-version blobs are
106    /// returned as `None` elements.
107    fn get_by_versioned_hashes_v3(
108        &self,
109        versioned_hashes: &[B256],
110    ) -> Result<Vec<Option<BlobAndProofV2>>, BlobStoreError>;
111
112    /// Return the [`BlobCellsAndProofsV1`]s for a list of blob versioned hashes and requested cell
113    /// indices.
114    ///
115    /// The response is always the same length as the request. Missing or older-version blobs are
116    /// returned as `None` elements.
117    fn get_by_versioned_hashes_v4(
118        &self,
119        versioned_hashes: &[B256],
120        indices_bitarray: B128,
121    ) -> Result<Vec<Option<BlobCellsAndProofsV1>>, BlobStoreError>;
122
123    /// Returns all requested cells for all blobs belonging to the transaction.
124    ///
125    /// The `indices_bitarray` is applied independently to every blob in the tx.
126    ///
127    /// Returned cells are flattened in blob order, then cell-index order.
128    ///
129    /// Example:
130    /// If the tx contains blobs `[blob0, blob1]` and the requested indices are
131    /// `[2, 5, 9]`, the returned vector is:
132    ///
133    /// ```text
134    /// [
135    ///   blob0_cell2,
136    ///   blob0_cell5,
137    ///   blob0_cell9,
138    ///   blob1_cell2,
139    ///   blob1_cell5,
140    ///   blob1_cell9,
141    /// ]
142    /// ```
143    fn get_cells(
144        &self,
145        tx_hash: TxHash,
146        indices_bitarray: B128,
147    ) -> Result<Option<Vec<Cell>>, BlobStoreError>;
148
149    /// Data size of all transactions in the blob store.
150    fn data_size_hint(&self) -> Option<usize>;
151
152    /// How many blobs are in the blob store.
153    fn blobs_len(&self) -> usize;
154}
155
156/// Error variants that can occur when interacting with a blob store.
157#[derive(Debug, thiserror::Error)]
158pub enum BlobStoreError {
159    /// Thrown if the blob sidecar is not found for a given transaction hash but was required.
160    #[error("blob sidecar not found for transaction {0:?}")]
161    MissingSidecar(B256),
162    /// Failed to decode the stored blob data.
163    #[error("failed to decode blob data: {0}")]
164    DecodeError(#[from] alloy_rlp::Error),
165    /// Other implementation specific error.
166    #[error(transparent)]
167    Other(Box<dyn core::error::Error + Send + Sync>),
168}
169
170/// Keeps track of the size of the blob store.
171#[derive(Debug, Default)]
172pub(crate) struct BlobStoreSize {
173    data_size: AtomicUsize,
174    num_blobs: AtomicUsize,
175}
176
177impl BlobStoreSize {
178    #[inline]
179    pub(crate) fn add_size(&self, add: usize) {
180        self.data_size.fetch_add(add, Ordering::Relaxed);
181    }
182
183    #[inline]
184    pub(crate) fn sub_size(&self, sub: usize) {
185        let _ = self.data_size.fetch_update(Ordering::Relaxed, Ordering::Relaxed, |current| {
186            Some(current.saturating_sub(sub))
187        });
188    }
189
190    #[inline]
191    pub(crate) fn update_len(&self, len: usize) {
192        self.num_blobs.store(len, Ordering::Relaxed);
193    }
194
195    #[inline]
196    pub(crate) fn inc_len(&self, add: usize) {
197        self.num_blobs.fetch_add(add, Ordering::Relaxed);
198    }
199
200    #[inline]
201    pub(crate) fn sub_len(&self, sub: usize) {
202        let _ = self.num_blobs.fetch_update(Ordering::Relaxed, Ordering::Relaxed, |current| {
203            Some(current.saturating_sub(sub))
204        });
205    }
206
207    #[inline]
208    pub(crate) fn data_size(&self) -> usize {
209        self.data_size.load(Ordering::Relaxed)
210    }
211
212    #[inline]
213    pub(crate) fn blobs_len(&self) -> usize {
214        self.num_blobs.load(Ordering::Relaxed)
215    }
216}
217
218impl PartialEq for BlobStoreSize {
219    fn eq(&self, other: &Self) -> bool {
220        self.data_size.load(Ordering::Relaxed) == other.data_size.load(Ordering::Relaxed) &&
221            self.num_blobs.load(Ordering::Relaxed) == other.num_blobs.load(Ordering::Relaxed)
222    }
223}
224
225/// Statistics for the cleanup operation.
226#[derive(Debug, Clone, Default, PartialEq, Eq)]
227pub struct BlobStoreCleanupStat {
228    /// the number of successfully deleted blobs
229    pub delete_succeed: usize,
230    /// the number of failed deletions
231    pub delete_failed: usize,
232}
233
234#[cfg(test)]
235mod tests {
236    use super::*;
237
238    #[expect(dead_code)]
239    struct DynStore {
240        store: Box<dyn BlobStore>,
241    }
242}
reth_transaction_pool/blobstore/mod.rs

reth_transaction_pool/blobstore/
mod.rs
