reth_storage_api/
receipts.rs

1use crate::BlockIdReader;
2use alloc::vec::Vec;
3use alloy_eips::{BlockHashOrNumber, BlockId, BlockNumberOrTag};
4use alloy_primitives::{BlockNumber, TxHash, TxNumber};
5use core::ops::{RangeBounds, RangeInclusive};
6use reth_primitives_traits::Receipt;
7use reth_storage_errors::provider::ProviderResult;
8
9/// A helper type alias to access [`ReceiptProvider::Receipt`].
10pub type ProviderReceipt<P> = <P as ReceiptProvider>::Receipt;
11
12/// Client trait for fetching receipt data.
13#[auto_impl::auto_impl(&, Arc)]
14pub trait ReceiptProvider: Send + Sync {
15    /// The receipt type.
16    type Receipt: Receipt;
17
18    /// Get receipt by transaction number
19    ///
20    /// Returns `None` if the transaction is not found.
21    fn receipt(&self, id: TxNumber) -> ProviderResult<Option<Self::Receipt>>;
22
23    /// Get receipt by transaction hash.
24    ///
25    /// Returns `None` if the transaction is not found.
26    fn receipt_by_hash(&self, hash: TxHash) -> ProviderResult<Option<Self::Receipt>>;
27
28    /// Get receipts by block num or hash.
29    ///
30    /// Returns `None` if the block is not found.
31    fn receipts_by_block(
32        &self,
33        block: BlockHashOrNumber,
34    ) -> ProviderResult<Option<Vec<Self::Receipt>>>;
35
36    /// Get receipts by tx range.
37    fn receipts_by_tx_range(
38        &self,
39        range: impl RangeBounds<TxNumber>,
40    ) -> ProviderResult<Vec<Self::Receipt>>;
41
42    /// Get receipts by block range.
43    ///
44    /// Returns a vector where each element contains all receipts for a block in the range.
45    /// The outer vector index corresponds to blocks in the range (`block_range.start()` + index).
46    /// Empty blocks will have empty inner vectors.
47    ///
48    /// This is more efficient than calling `receipts_by_block` multiple times for contiguous ranges
49    /// because it can leverage the underlying `receipts_by_tx_range` for the entire transaction
50    /// span.
51    fn receipts_by_block_range(
52        &self,
53        block_range: RangeInclusive<BlockNumber>,
54    ) -> ProviderResult<Vec<Vec<Self::Receipt>>>;
55}
56
57/// Trait extension for `ReceiptProvider`, for types that implement `BlockId` conversion.
58///
59/// The `Receipt` trait should be implemented on types that can retrieve receipts from either
60/// a block number or hash. However, it might be desirable to fetch receipts from a `BlockId` type,
61/// which can be a number, hash, or tag such as `BlockNumberOrTag::Safe`.
62///
63/// Resolving tags requires keeping track of block hashes or block numbers associated with the tag,
64/// so this trait can only be implemented for types that implement `BlockIdReader`. The
65/// `BlockIdReader` methods should be used to resolve `BlockId`s to block numbers or hashes, and
66/// retrieving the receipts should be done using the type's `ReceiptProvider` methods.
67pub trait ReceiptProviderIdExt: ReceiptProvider + BlockIdReader {
68    /// Get receipt by block id
69    fn receipts_by_block_id(&self, block: BlockId) -> ProviderResult<Option<Vec<Self::Receipt>>> {
70        let id = match block {
71            BlockId::Hash(hash) => BlockHashOrNumber::Hash(hash.block_hash),
72            BlockId::Number(num_tag) => {
73                if let Some(num) = self.convert_block_number(num_tag)? {
74                    BlockHashOrNumber::Number(num)
75                } else {
76                    return Ok(None)
77                }
78            }
79        };
80
81        self.receipts_by_block(id)
82    }
83
84    /// Returns the block with the matching `BlockId` from the database.
85    ///
86    /// Returns `None` if block is not found.
87    fn receipts_by_number_or_tag(
88        &self,
89        number_or_tag: BlockNumberOrTag,
90    ) -> ProviderResult<Option<Vec<Self::Receipt>>> {
91        self.receipts_by_block_id(number_or_tag.into())
92    }
93}
reth_storage_api/receipts.rs

reth_storage_api/
receipts.rs
