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, utils::calculate_gas_used_and_next_log_index};
8use alloy_consensus::{BlockHeader, TxReceipt};
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::{transaction::ConvertReceiptInput, 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>>, Arc<Vec<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 pair of an [`Arc`] wrapped [`RecoveredBlock`] and a vector of
82/// [`NodePrimitives::Receipt`].
83pub type PendingBlockAndReceipts<N> = BlockAndReceipts<N>;
84
85/// Locally built pending block for `pending` tag.
86#[derive(Debug, Clone, Constructor)]
87pub struct PendingBlock<N: NodePrimitives> {
88    /// Timestamp when the pending block is considered outdated.
89    pub expires_at: Instant,
90    /// The receipts for the pending block
91    pub receipts: Arc<Vec<ReceiptTy<N>>>,
92    /// The locally built pending block with execution output.
93    pub executed_block: ExecutedBlock<N>,
94}
95
96impl<N: NodePrimitives> PendingBlock<N> {
97    /// Creates a new instance of [`PendingBlock`] with `executed_block` as its output that should
98    /// not be used past `expires_at`.
99    pub fn with_executed_block(expires_at: Instant, executed_block: ExecutedBlock<N>) -> Self {
100        Self {
101            expires_at,
102            receipts: Arc::new(
103                executed_block.execution_output.receipts.iter().flatten().cloned().collect(),
104            ),
105            executed_block,
106        }
107    }
108
109    /// Returns the locally built pending [`RecoveredBlock`].
110    pub const fn block(&self) -> &Arc<RecoveredBlock<BlockTy<N>>> {
111        &self.executed_block.recovered_block
112    }
113
114    /// Converts this [`PendingBlock`] into a pair of [`RecoveredBlock`] and a vector of
115    /// [`NodePrimitives::Receipt`]s, taking self.
116    pub fn into_block_and_receipts(self) -> PendingBlockAndReceipts<N> {
117        BlockAndReceipts { block: self.executed_block.recovered_block, receipts: self.receipts }
118    }
119
120    /// Returns a pair of [`RecoveredBlock`] and a vector of  [`NodePrimitives::Receipt`]s by
121    /// cloning from borrowed self.
122    pub fn to_block_and_receipts(&self) -> PendingBlockAndReceipts<N> {
123        BlockAndReceipts {
124            block: self.executed_block.recovered_block.clone(),
125            receipts: self.receipts.clone(),
126        }
127    }
128
129    /// Returns a hash of the parent block for this `executed_block`.
130    pub fn parent_hash(&self) -> BlockHash {
131        self.executed_block.recovered_block().parent_hash()
132    }
133
134    /// Finds a transaction by hash and returns it along with its corresponding receipt.
135    ///
136    /// Returns `None` if the transaction is not found in this block.
137    pub fn find_transaction_and_receipt_by_hash(
138        &self,
139        tx_hash: TxHash,
140    ) -> Option<(IndexedTx<'_, N::Block>, &N::Receipt)> {
141        let indexed_tx = self.executed_block.recovered_block().find_indexed(tx_hash)?;
142        let receipt = self.receipts.get(indexed_tx.index())?;
143        Some((indexed_tx, receipt))
144    }
145
146    /// Returns the rpc transaction receipt for the given transaction hash if it exists.
147    ///
148    /// This uses the given converter to turn [`Self::find_transaction_and_receipt_by_hash`] into
149    /// the rpc format.
150    pub fn find_and_convert_transaction_receipt<C>(
151        &self,
152        tx_hash: TxHash,
153        converter: &C,
154    ) -> Option<Result<<C::Network as RpcTypes>::Receipt, C::Error>>
155    where
156        C: RpcConvert<Primitives = N>,
157    {
158        let (tx, receipt) = self.find_transaction_and_receipt_by_hash(tx_hash)?;
159        let meta = tx.meta();
160        let all_receipts = &self.receipts;
161
162        let (gas_used, next_log_index) =
163            calculate_gas_used_and_next_log_index(meta.index, all_receipts);
164
165        converter
166            .convert_receipts_with_block(
167                vec![ConvertReceiptInput {
168                    tx: tx.recovered_tx(),
169                    gas_used: receipt.cumulative_gas_used() - gas_used,
170                    receipt: receipt.clone(),
171                    next_log_index,
172                    meta,
173                }],
174                self.executed_block.sealed_block(),
175            )
176            .map(|mut receipts| receipts.pop())
177            .transpose()
178    }
179}
180
181impl<N: NodePrimitives> From<PendingBlock<N>> for BlockState<N> {
182    fn from(pending_block: PendingBlock<N>) -> Self {
183        Self::new(pending_block.executed_block)
184    }
185}
reth_rpc_eth_types/pending_block.rs

reth_rpc_eth_types/
pending_block.rs
