reth_network/
import.rs

1//! This module provides an abstraction over block import in the form of the `BlockImport` trait.
2
3use crate::message::NewBlockMessage;
4use reth_eth_wire::NewBlock;
5use reth_eth_wire_types::broadcast::NewBlockHashes;
6use reth_network_peers::PeerId;
7use std::{
8    error::Error,
9    task::{Context, Poll},
10};
11
12/// Abstraction over block import.
13pub trait BlockImport<B = NewBlock>: std::fmt::Debug + Send + Sync {
14    /// Invoked for a received block announcement from the peer.
15    ///
16    /// For a `NewBlock` message:
17    /// > When a `NewBlock` announcement message is received from a peer, the client first verifies
18    /// > the basic header validity of the block, checking whether the proof-of-work value is valid.
19    ///
20    /// For a `NewBlockHashes` message, hash announcement should be processed accordingly.
21    ///
22    /// The results are expected to be returned via [`BlockImport::poll`].
23    fn on_new_block(&mut self, peer_id: PeerId, incoming_block: NewBlockEvent<B>);
24
25    /// Returns the results of a [`BlockImport::on_new_block`]
26    fn poll(&mut self, cx: &mut Context<'_>) -> Poll<BlockImportEvent<B>>;
27}
28
29/// Represents different types of block announcement events from the network.
30#[derive(Debug, Clone)]
31pub enum NewBlockEvent<B = NewBlock> {
32    /// A new full block announcement
33    Block(NewBlockMessage<B>),
34    /// Only the hashes of new blocks
35    Hashes(NewBlockHashes),
36}
37
38/// Represents different types of block import events
39#[derive(Debug)]
40pub enum BlockImportEvent<B = reth_ethereum_primitives::Block> {
41    /// General block announcement and validation status
42    Announcement(BlockValidation<B>),
43    /// Result of a peer-specific block import
44    Outcome(BlockImportOutcome<B>),
45}
46
47/// Outcome of the [`BlockImport`]'s block handling.
48#[derive(Debug)]
49pub struct BlockImportOutcome<B = reth_ethereum_primitives::Block> {
50    /// Sender of the block announcement message.
51    pub peer: PeerId,
52    /// The result after validating the block
53    pub result: Result<BlockValidation<B>, BlockImportError>,
54}
55
56/// Represents the successful validation of a received block announcement.
57#[derive(Debug)]
58pub enum BlockValidation<B> {
59    /// Basic Header validity check, after which the block should be relayed to peers via a
60    /// `NewBlock` message
61    ValidHeader {
62        /// received block
63        block: NewBlockMessage<B>,
64    },
65    /// Successfully imported: state-root matches after execution. The block should be relayed via
66    /// `NewBlockHashes`
67    ValidBlock {
68        /// validated block.
69        block: NewBlockMessage<B>,
70    },
71}
72
73/// Represents the error case of a failed block import
74#[derive(Debug, thiserror::Error)]
75pub enum BlockImportError {
76    /// Consensus error
77    #[error(transparent)]
78    Consensus(#[from] reth_consensus::ConsensusError),
79    /// Other error
80    #[error(transparent)]
81    Other(#[from] Box<dyn Error + Send + Sync>),
82}
83
84/// An implementation of `BlockImport` used in Proof-of-Stake consensus that does nothing.
85///
86/// Block propagation over devp2p is invalid in POS: [EIP-3675](https://eips.ethereum.org/EIPS/eip-3675#devp2p)
87#[derive(Debug, Default)]
88#[non_exhaustive]
89pub struct ProofOfStakeBlockImport;
90
91impl<B> BlockImport<B> for ProofOfStakeBlockImport {
92    fn on_new_block(&mut self, _peer_id: PeerId, _incoming_block: NewBlockEvent<B>) {}
93
94    fn poll(&mut self, _cx: &mut Context<'_>) -> Poll<BlockImportEvent<B>> {
95        Poll::Pending
96    }
97}
reth_network/import.rs

reth_network/
import.rs
