Struct BeaconConsensusEngine

pub struct BeaconConsensusEngine<N, BT, Client>
where
    N: EngineNodeTypes,
    Client: EthBlockClient,
    BT: BlockchainTreeEngine + BlockReader + BlockIdReader + CanonChainTracker + StageCheckpointReader,
{ /* private fields */ }

The beacon consensus engine is the driver that switches between historical and live sync.

The beacon consensus engine is itself driven by messages from the Consensus Layer, which are received by Engine API (JSON-RPC).

The consensus engine is idle until it receives the first BeaconEngineMessage::ForkchoiceUpdated message from the CL which would initiate the sync. At first, the consensus engine would run the [Pipeline] until the latest known block hash. Afterward, it would attempt to create/restore the BlockchainTreeEngine from the blocks that are currently available. In case the restoration is successful, the consensus engine would run in a live sync mode, populating the BlockchainTreeEngine with new blocks as they arrive via engine API and downloading any missing blocks from the network to fill potential gaps.

The consensus engine has two data input sources:

New Payload (engine_newPayloadV{})

The engine receives new payloads from the CL. If the payload is connected to the canonical chain, it will be fully validated added to a chain in the BlockchainTreeEngine: VALID

If the payload’s chain is disconnected (at least 1 block is missing) then it will be buffered: SYNCING (BlockStatus::Disconnected).

Forkchoice Update (FCU) (engine_forkchoiceUpdatedV{})

This contains the latest forkchoice state and the payload attributes. The engine will attempt to make a new canonical chain based on the head_hash of the update and trigger payload building if the payload_attrs are present and the FCU is VALID.

The head_hash forms a chain by walking backwards from the head_hash towards the canonical blocks of the chain.

Making a new canonical chain can result in the following relevant outcomes:

The chain is connected

All blocks of the head_hash’s chain are present in the BlockchainTreeEngine and are committed to the canonical chain. This also includes reorgs.

The chain is disconnected

In this case the BlockchainTreeEngine doesn’t know how the new chain connects to the existing canonical chain. It could be a simple commit (new blocks extend the current head) or a re-org that requires unwinding the canonical chain.

This further distinguishes between two variants:

head_hash’s block exists

The head_hash’s block was already received/downloaded, but at least one block is missing to form a connected chain. The engine will attempt to download the missing blocks from the network by walking backwards (parent_hash), and then try to make the block canonical as soon as the chain becomes connected.

However, it still can be the case that the chain and the FCU is INVALID.

head_hash block is missing

This is similar to the previous case, but the head_hash’s block is missing. At which point the engine doesn’t know where the new head will point to: new chain could be a re-org or a simple commit. The engine will download the missing head first and then proceed as in the previous case.

Panics

If the future is polled more than once. Leads to undefined state.

Note: soon deprecated. See reth_engine_service::EngineService.

Implementations

impl<N, BT, Client> BeaconConsensusEngine<N, BT, Client>

where BT: BlockchainTreeEngine + BlockReader<Block = <<N as NodeTypes>::Primitives as NodePrimitives>::Block, Header = <<N as NodeTypes>::Primitives as NodePrimitives>::BlockHeader> + BlockIdReader + CanonChainTracker<Header = <<N as NodeTypes>::Primitives as NodePrimitives>::BlockHeader> + StageCheckpointReader + ChainSpecProvider<ChainSpec = <N as NodeTypes>::ChainSpec> + 'static, N: TreeNodeTypes, Client: EthBlockClient + 'static,

pub fn new( client: Client, pipeline: Pipeline<N>, blockchain: BT, task_spawner: Box<dyn TaskSpawner>, sync_state_updater: Box<dyn NetworkSyncUpdater>, max_block: Option<u64>, payload_builder: PayloadBuilderHandle<<N as NodeTypesWithEngine>::Engine>, target: Option<FixedBytes<32>>, pipeline_run_threshold: u64, hooks: EngineHooks, ) -> Result<(BeaconConsensusEngine<N, BT, Client>, BeaconConsensusEngineHandle<<N as NodeTypesWithEngine>::Engine>), RethError>

Create a new instance of the BeaconConsensusEngine.

pub fn with_channel( client: Client, pipeline: Pipeline<N>, blockchain: BT, task_spawner: Box<dyn TaskSpawner>, sync_state_updater: Box<dyn NetworkSyncUpdater>, max_block: Option<u64>, payload_builder: PayloadBuilderHandle<<N as NodeTypesWithEngine>::Engine>, target: Option<FixedBytes<32>>, pipeline_run_threshold: u64, to_engine: UnboundedSender<BeaconEngineMessage<<N as NodeTypesWithEngine>::Engine>>, engine_message_stream: Pin<Box<dyn Stream<Item = BeaconEngineMessage<<N as NodeTypesWithEngine>::Engine>> + Send>>, hooks: EngineHooks, ) -> Result<(BeaconConsensusEngine<N, BT, Client>, BeaconConsensusEngineHandle<<N as NodeTypesWithEngine>::Engine>), RethError>

Create a new instance of the BeaconConsensusEngine using the given channel to configure the BeaconEngineMessage communication channel.

By default the engine is started with idle pipeline. The pipeline can be launched immediately in one of the following ways descending in priority:

• Explicit Option::Some target block hash provided via a constructor argument.
• The process was previously interrupted amidst the pipeline run. This is checked by comparing the checkpoints of the first ([StageId::Headers]) and last ([StageId::Finish]) stages. In this case, the latest available header in the database is used as the target.

Propagates any database related error.

pub fn handle( &self, ) -> BeaconConsensusEngineHandle<<N as NodeTypesWithEngine>::Engine>

Returns a new BeaconConsensusEngineHandle that can be cloned and shared.

The BeaconConsensusEngineHandle can be used to interact with this BeaconConsensusEngine

Trait Implementations

impl<N, BT, Client> Future for BeaconConsensusEngine<N, BT, Client>

where Client: EthBlockClient + 'static, BT: BlockchainTreeEngine + BlockReader<Block = <<N as NodeTypes>::Primitives as NodePrimitives>::Block, Header = <<N as NodeTypes>::Primitives as NodePrimitives>::BlockHeader> + BlockIdReader + CanonChainTracker<Header = <<N as NodeTypes>::Primitives as NodePrimitives>::BlockHeader> + StageCheckpointReader + ChainSpecProvider<ChainSpec = <N as NodeTypes>::ChainSpec> + Unpin + 'static, N: TreeNodeTypes,

On initialization, the consensus engine will poll the message receiver and return Poll::Pending until the first forkchoice update message is received.

As soon as the consensus engine receives the first forkchoice updated message and updates the local forkchoice state, it will launch the pipeline to sync to the head hash. While the pipeline is syncing, the consensus engine will keep processing messages from the receiver and forwarding them to the blockchain tree.

type Output = Result<(), BeaconConsensusEngineError>

The type of value produced on completion.

fn poll( self: Pin<&mut BeaconConsensusEngine<N, BT, Client>>, cx: &mut Context<'_>, ) -> Poll<<BeaconConsensusEngine<N, BT, Client> as Future>::Output>

Attempts to resolve the future to a final value, registering the current task for wakeup if the value is not yet available.

Layout

Note: Unable to compute type layout, possibly due to this type having generic parameters. Layout can only be computed for concrete, fully-instantiated types.