Crate reth_exex

Execution extensions (ExEx).

An execution extension is a task that listens to state changes of the node.

Some examples of such state derives are rollups, bridges, and indexers.

An ExEx is a Future resolving to a Result<()> that is run indefinitely alongside the node.

ExEx’s are initialized using an async closure that resolves to the ExEx; this closure gets passed an ExExContext where it is possible to spawn additional tasks and modify Reth.

Most ExEx’s will want to derive their state from the CanonStateNotification channel given in ExExContext. A new notification is emitted whenever blocks are executed in live and historical sync.

Pruning

ExEx’s SHOULD emit an ExExEvent::FinishedHeight event to signify what blocks have been processed. This event is used by Reth to determine what state can be pruned.

An ExEx will only receive notifications for blocks greater than the block emitted in the event. To clarify: if the ExEx emits ExExEvent::FinishedHeight(0) it will receive notifications for any block_number > 0.

Examples, Assumptions, and Invariants

Examples

Simple Indexer ExEx

use alloy_consensus::BlockHeader;
use futures::StreamExt;
use reth_exex::ExExContext;
use reth_node_api::FullNodeComponents;
use reth_provider::CanonStateNotification;

async fn my_indexer<N: FullNodeComponents>(
    mut ctx: ExExContext<N>,
) -> Result<(), Box<dyn std::error::Error>> {
    // Subscribe to canonical state notifications

    while let Some(Ok(notification)) = ctx.notifications.next().await {
        if let Some(committed) = notification.committed_chain() {
            for block in committed.blocks_iter() {
                // Index or process block data
                println!("Processed block: {}", block.number());
            }

            // Signal completion for pruning
            ctx.send_finished_height(committed.tip().num_hash());
        }
    }

    Ok(())
}

Assumptions

• ExExs run indefinitely alongside Reth
• ExExs receive canonical state notifications for block execution
• ExExs should handle potential network or database errors gracefully
• ExExs must emit FinishedHeight events for proper state pruning

Invariants

• An ExEx must not block the main Reth execution
• Notifications are processed in canonical order
• ExExs should be able to recover from temporary failures
• Memory and resource usage must be controlled

Performance Considerations

• Minimize blocking operations
• Use efficient data structures for state tracking
• Implement proper error handling and logging
• Consider batching operations for better performance

Modules

serde_bincode_compatserde and serde-bincode-compat

Bincode-compatible serde implementations for commonly used ExEx types.

Structs

BackfillJob

Backfill job started for a specific range.

BackfillJobFactory

Factory for creating new backfill jobs.

BlockCache

The block cache of the WAL.

ExExContext

Captures the context that an ExEx has access to.

ExExContextDyn

Captures the context that an ExEx has access to.

ExExHandle

A handle to an ExEx used by the ExExManager to communicate with ExEx’s.

ExExHead

A head of the ExEx. It contains the highest host block committed to the internal ExEx state. I.e. the latest block that the ExEx has fully processed.

ExExManager

The execution extension manager.

ExExManagerHandle

A handle to communicate with the ExExManager.

ExExManagerMetrics

Metrics for the ExEx manager.

ExExNotifications

A stream of ExExNotifications. The stream will emit notifications for all blocks. If the stream is configured with a head via ExExNotifications::set_with_head or ExExNotifications::with_head, it will run backfill jobs to catch up to the node head.

ExExNotificationsWithHead

A stream of ExExNotifications. The stream will only emit notifications for blocks that are committed or reverted after the given head. The head is the ExEx’s latest view of the host chain.

ExExNotificationsWithoutHead

A stream of ExExNotifications. The stream will emit notifications for all blocks.

SingleBlockBackfillJob

Single block Backfill job started for a specific range.

Storage

The underlying WAL storage backed by a directory of files.

StreamBackfillJob

Stream for processing backfill jobs asynchronously.

Wal

WAL is a write-ahead log (WAL) that stores the notifications sent to ExExes.

WalHandle

A read-only handle to the WAL that can be shared.

Enums

ExExEvent

Events emitted by an ExEx.

ExExNotification

Notifications sent to an ExEx.

ExExNotificationSource

The source of the notification.

FinishedExExHeight

The finished height of all ExEx’s.

WalError

Wal Error types

Constants

DEFAULT_EXEX_MANAGER_CAPACITY

Default max size of the internal state notifications buffer.

WAL_BLOCKS_WARNING

The maximum number of blocks allowed in the WAL before emitting a warning.

Traits

ExExNotificationsStream

A trait, that represents a stream of ExExNotifications. The stream will emit notifications for all blocks. If the stream is configured with a head via ExExNotifications::set_with_head or ExExNotifications::with_head, it will run backfill jobs to catch up to the node head.

Type Aliases

WalResult

Wal Result type.