feat: exex manager (paradigmxyz#7340)

Co-authored-by: Alexey Shekhirin <[email protected]>

crates/exex/Cargo.toml

@@ -12,10 +12,22 @@ description = "Execution extensions for Reth"
 workspace = true
 
 [dependencies]
+## reth
 reth-config.workspace = true
+reth-metrics.workspace = true
 reth-node-api.workspace = true
 reth-node-core.workspace = true
 reth-primitives.workspace = true
 reth-provider.workspace = true
 reth-tasks.workspace = true
+reth-tracing.workspace = true
+
+## async
+futures.workspace = true
 tokio.workspace = true
+tokio-stream.workspace = true
+tokio-util.workspace = true
+
+## misc
+eyre.workspace = true
+metrics.workspace = true

crates/exex/src/lib.rs

@@ -1,6 +1,31 @@
-//! Execution extensions.
+// todo: expand this (examples, assumptions, invariants)
+//! Execution extensions (ExEx).
 //!
-//! TBD
+//! An execution extension is a task that derives its state from Reth's state.
+//!
+//! 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 Reth.
+//!
+//! 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`.
+//!
+//! [`Future`]: std::future::Future
+//! [`ExExContext`]: crate::ExExContext
+//! [`CanonStateNotification`]: reth_provider::CanonStateNotification
 #![doc(
     html_logo_url = "https://raw.githubusercontent.com/paradigmxyz/reth/main/assets/reth-docs.png",
     html_favicon_url = "https://avatars0.githubusercontent.com/u/97369466?s=256",
@@ -14,3 +39,6 @@ pub use context::*;
 
 mod event;
 pub use event::*;
+
+mod manager;
+pub use manager::*;