reth_rpc_eth_types/
pending_block.rs

1//! Helper types for `reth_rpc_eth_api::EthApiServer` implementation.
2//!
3//! Types used in block building.
4
5use std::{sync::Arc, time::Instant};
6
7use crate::block::{BlockAndReceipts, SharedReceipts};
8use alloy_consensus::BlockHeader;
9use alloy_eips::{BlockId, BlockNumberOrTag};
10use alloy_primitives::{BlockHash, TxHash, B256};
11use derive_more::Constructor;
12use reth_chain_state::{BlockState, ExecutedBlock};
13use reth_ethereum_primitives::Receipt;
14use reth_evm::{ConfigureEvm, EvmEnvFor};
15use reth_primitives_traits::{
16    Block, BlockTy, IndexedTx, NodePrimitives, ReceiptTy, RecoveredBlock, SealedHeader,
17};
18use reth_rpc_convert::{RpcConvert, RpcTypes};
19
20/// Configured [`reth_evm::EvmEnv`] for a pending block.
21#[derive(Debug, Clone, Constructor)]
22pub struct PendingBlockEnv<Evm: ConfigureEvm> {
23    /// Configured [`reth_evm::EvmEnv`] for the pending block.
24    pub evm_env: EvmEnvFor<Evm>,
25    /// Origin block for the config
26    pub origin: PendingBlockEnvOrigin<BlockTy<Evm::Primitives>, ReceiptTy<Evm::Primitives>>,
27}
28
29/// The origin for a configured [`PendingBlockEnv`]
30#[derive(Clone, Debug)]
31pub enum PendingBlockEnvOrigin<B: Block = reth_ethereum_primitives::Block, R = Receipt> {
32    /// The pending block as received from the CL.
33    ActualPending(Arc<RecoveredBlock<B>>, SharedReceipts<R>),
34    /// The _modified_ header of the latest block.
35    ///
36    /// This derives the pending state based on the latest header by modifying:
37    ///  - the timestamp
38    ///  - the block number
39    ///  - fees
40    DerivedFromLatest(SealedHeader<B::Header>),
41}
42
43impl<B: Block, R> PendingBlockEnvOrigin<B, R> {
44    /// Returns true if the origin is the actual pending block as received from the CL.
45    pub const fn is_actual_pending(&self) -> bool {
46        matches!(self, Self::ActualPending(_, _))
47    }
48
49    /// Consumes the type and returns the actual pending block.
50    pub fn into_actual_pending(self) -> Option<Arc<RecoveredBlock<B>>> {
51        match self {
52            Self::ActualPending(block, _) => Some(block),
53            _ => None,
54        }
55    }
56
57    /// Returns the [`BlockId`] that represents the state of the block.
58    ///
59    /// If this is the actual pending block, the state is the "Pending" tag, otherwise we can safely
60    /// identify the block by its hash (latest block).
61    pub fn state_block_id(&self) -> BlockId {
62        match self {
63            Self::ActualPending(_, _) => BlockNumberOrTag::Pending.into(),
64            Self::DerivedFromLatest(latest) => BlockId::Hash(latest.hash().into()),
65        }
66    }
67
68    /// Returns the hash of the block the pending block should be built on.
69    ///
70    /// For the [`PendingBlockEnvOrigin::ActualPending`] this is the parent hash of the block.
71    /// For the [`PendingBlockEnvOrigin::DerivedFromLatest`] this is the hash of the _latest_
72    /// header.
73    pub fn build_target_hash(&self) -> B256 {
74        match self {
75            Self::ActualPending(block, _) => block.header().parent_hash(),
76            Self::DerivedFromLatest(latest) => latest.hash(),
77        }
78    }
79}
80
81/// A type alias for a shared [`RecoveredBlock`] and its receipts.
82pub type PendingBlockAndReceipts<N> = BlockAndReceipts<N>;
83
84/// Locally built pending block for `pending` tag.
85#[derive(Debug, Clone, Constructor)]
86pub struct PendingBlock<N: NodePrimitives> {
87    /// Timestamp when the pending block is considered outdated.
88    pub expires_at: Instant,
89    /// The receipts for the pending block
90    pub receipts: SharedReceipts<ReceiptTy<N>>,
91    /// The locally built pending block with execution output.
92    pub executed_block: ExecutedBlock<N>,
93}
94
95impl<N: NodePrimitives> PendingBlock<N> {
96    /// Creates a new instance of [`PendingBlock`] with `executed_block` as its output that should
97    /// not be used past `expires_at`.
98    pub fn with_executed_block(expires_at: Instant, executed_block: ExecutedBlock<N>) -> Self {
99        Self {
100            expires_at,
101            receipts: Arc::clone(&executed_block.execution_output).into(),
102            executed_block,
103        }
104    }
105
106    /// Returns the locally built pending [`RecoveredBlock`].
107    pub const fn block(&self) -> &Arc<RecoveredBlock<BlockTy<N>>> {
108        &self.executed_block.recovered_block
109    }
110
111    /// Converts this [`PendingBlock`] into a pair of [`RecoveredBlock`] and a vector of
112    /// [`NodePrimitives::Receipt`]s, taking self.
113    pub fn into_block_and_receipts(self) -> PendingBlockAndReceipts<N> {
114        BlockAndReceipts { block: self.executed_block.recovered_block, receipts: self.receipts }
115    }
116
117    /// Returns a pair of [`RecoveredBlock`] and a vector of  [`NodePrimitives::Receipt`]s by
118    /// cloning from borrowed self.
119    pub fn to_block_and_receipts(&self) -> PendingBlockAndReceipts<N> {
120        BlockAndReceipts {
121            block: self.executed_block.recovered_block.clone(),
122            receipts: self.receipts.clone(),
123        }
124    }
125
126    /// Returns a hash of the parent block for this `executed_block`.
127    pub fn parent_hash(&self) -> BlockHash {
128        self.executed_block.recovered_block().parent_hash()
129    }
130
131    /// Finds a transaction by hash and returns it along with its corresponding receipt.
132    ///
133    /// Returns `None` if the transaction is not found in this block.
134    pub fn find_transaction_and_receipt_by_hash(
135        &self,
136        tx_hash: TxHash,
137    ) -> Option<(IndexedTx<'_, N::Block>, &N::Receipt)> {
138        let indexed_tx = self.executed_block.recovered_block().find_indexed(tx_hash)?;
139        let receipt = self.receipts.get(indexed_tx.index())?;
140        Some((indexed_tx, receipt))
141    }
142
143    /// Returns the rpc transaction receipt for the given transaction hash if it exists.
144    ///
145    /// This uses the given converter to turn [`Self::find_transaction_and_receipt_by_hash`] into
146    /// the rpc format.
147    pub fn find_and_convert_transaction_receipt<C>(
148        &self,
149        tx_hash: TxHash,
150        converter: &C,
151    ) -> Option<Result<<C::Network as RpcTypes>::Receipt, C::Error>>
152    where
153        C: RpcConvert<Primitives = N>,
154    {
155        self.to_block_and_receipts().find_and_convert_transaction_receipt(tx_hash, converter)
156    }
157}
158
159impl<N: NodePrimitives> From<PendingBlock<N>> for BlockState<N> {
160    fn from(pending_block: PendingBlock<N>) -> Self {
161        Self::new(pending_block.executed_block)
162    }
163}
reth_rpc_eth_types/pending_block.rs

reth_rpc_eth_types/
pending_block.rs
