[hackathon] feat: add HostNotifier trait and decouple node from ExExContext

Cargo.toml

@@ -40,6 +40,7 @@ signet-genesis = { version = "0.16.0-rc.7", path = "crates/genesis" }
 signet-node = { version = "0.16.0-rc.7", path = "crates/node" }
 signet-node-config = { version = "0.16.0-rc.7", path = "crates/node-config" }
 signet-node-tests = { version = "0.16.0-rc.7", path = "crates/node-tests" }
+signet-node-types = { version = "0.16.0-rc.7", path = "crates/node-types" }
 signet-rpc = { version = "0.16.0-rc.7", path = "crates/rpc" }
 
 init4-bin-base = { version = "0.18.0-rc.8", features = ["alloy"] }

crates/node-config/Cargo.toml

@@ -18,8 +18,6 @@ init4-bin-base.workspace = true
 
 reth.workspace = true
 reth-chainspec.workspace = true
-reth-exex.workspace = true
-reth-node-api.workspace = true
 alloy.workspace = true
 
 eyre.workspace = true

crates/node-config/src/core.rs

@@ -1,9 +1,9 @@
 use crate::StorageConfig;
 use alloy::genesis::Genesis;
 use init4_bin_base::utils::{calc::SlotCalculator, from_env::FromEnv};
+use reth::primitives::NodePrimitives;
 use reth::providers::providers::StaticFileProvider;
 use reth_chainspec::ChainSpec;
-use reth_node_api::NodePrimitives;
 use signet_blobber::BlobFetcherConfig;
 use signet_genesis::GenesisSpec;
 use signet_types::constants::{ConfigError, SignetSystemConstants};

crates/node-config/src/lib.rs

@@ -14,7 +14,8 @@
 mod core;
 pub use core::{SIGNET_NODE_DEFAULT_HTTP_PORT, SignetNodeConfig};
 
-mod rpc;
+// NB: RPC config merging (previously `merge_rpc_configs`) is now the
+// responsibility of the host adapter crate (e.g. `signet-host-reth`).
 
 mod storage;
 pub use storage::StorageConfig;

crates/node-types/Cargo.toml

@@ -0,0 +1,13 @@
+[package]
+name = "signet-node-types"
+description = "Trait abstractions for the signet node's host chain interface."
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+authors.workspace = true
+license.workspace = true
+homepage.workspace = true
+repository.workspace = true
+
+[dependencies]
+signet-extract.workspace = true

crates/node-types/README.md

@@ -0,0 +1,3 @@
+# signet-node-types
+
+Trait abstractions for the signet node's host chain interface.

crates/node-types/src/lib.rs

@@ -0,0 +1,18 @@
+#![doc = include_str!("../README.md")]
+#![warn(
+    missing_copy_implementations,
+    missing_debug_implementations,
+    missing_docs,
+    unreachable_pub,
+    clippy::missing_const_for_fn,
+    rustdoc::all
+)]
+#![cfg_attr(not(test), warn(unused_crate_dependencies))]
+#![deny(unused_must_use, rust_2018_idioms)]
+#![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]
+
+mod notification;
+pub use notification::{HostNotification, HostNotificationKind};
+
+mod notifier;
+pub use notifier::HostNotifier;

crates/node-types/src/notification.rs

@@ -0,0 +1,118 @@
+use signet_extract::Extractable;
+use std::sync::Arc;
+
+/// A notification from the host chain, bundling a chain event with
+/// point-in-time block tag data. The safe/finalized block numbers are
+/// intentionally snapshotted at notification creation time rather than
+/// fetched live, because rollup safe/finalized tags are only updated
+/// after block processing completes.
+///
+/// # Examples
+///
+/// ```
+/// # use std::sync::Arc;
+/// # use signet_node_types::{HostNotification, HostNotificationKind};
+/// # fn example<C: signet_extract::Extractable>(chain: Arc<C>) {
+/// let notification = HostNotification {
+///     kind: HostNotificationKind::ChainCommitted { new: chain },
+///     safe_block_number: Some(100),
+///     finalized_block_number: Some(90),
+/// };
+///
+/// // Access the committed chain via the shortcut method.
+/// assert!(notification.committed_chain().is_some());
+/// assert!(notification.reverted_chain().is_none());
+/// # }
+/// ```
+#[derive(Debug, Clone)]
+pub struct HostNotification<C> {
+    /// The chain event (commit, revert, or reorg).
+    pub kind: HostNotificationKind<C>,
+    /// The host chain "safe" block number at the time of this notification.
+    pub safe_block_number: Option<u64>,
+    /// The host chain "finalized" block number at the time of this
+    /// notification.
+    pub finalized_block_number: Option<u64>,
+}
+
+impl<C: Extractable> HostNotification<C> {
+    /// Returns the committed chain, if any. Shortcut for
+    /// `self.kind.committed_chain()`.
+    pub const fn committed_chain(&self) -> Option<&Arc<C>> {
+        self.kind.committed_chain()
+    }
+
+    /// Returns the reverted chain, if any. Shortcut for
+    /// `self.kind.reverted_chain()`.
+    pub const fn reverted_chain(&self) -> Option<&Arc<C>> {
+        self.kind.reverted_chain()
+    }
+}
+
+/// The kind of chain event in a [`HostNotification`].
+///
+/// # Examples
+///
+/// ```
+/// # use std::sync::Arc;
+/// # use signet_node_types::HostNotificationKind;
+/// # fn example<C: signet_extract::Extractable>(old: Arc<C>, new: Arc<C>) {
+/// let kind = HostNotificationKind::ChainReorged {
+///     old: old.clone(),
+///     new: new.clone(),
+/// };
+/// # }
+/// ```
+#[derive(Debug, Clone)]
+pub enum HostNotificationKind<C> {
+    /// A new chain segment was committed.
+    ChainCommitted {
+        /// The newly committed chain segment.
+        new: Arc<C>,
+    },
+    /// A chain segment was reverted.
+    ChainReverted {
+        /// The reverted chain segment.
+        old: Arc<C>,
+    },
+    /// A chain reorg occurred: one segment was reverted and replaced by
+    /// another.
+    ChainReorged {
+        /// The reverted chain segment.
+        old: Arc<C>,
+        /// The newly committed chain segment.
+        new: Arc<C>,
+    },
+}
+
+impl<C: Extractable> HostNotificationKind<C> {
+    /// Returns the committed chain, if any.
+    ///
+    /// Returns `Some` for [`ChainCommitted`] and [`ChainReorged`], `None`
+    /// for [`ChainReverted`].
+    ///
+    /// [`ChainCommitted`]: HostNotificationKind::ChainCommitted
+    /// [`ChainReorged`]: HostNotificationKind::ChainReorged
+    /// [`ChainReverted`]: HostNotificationKind::ChainReverted
+    pub const fn committed_chain(&self) -> Option<&Arc<C>> {
+        match self {
+            Self::ChainCommitted { new } | Self::ChainReorged { new, .. } => Some(new),
+            Self::ChainReverted { .. } => None,
+        }
+    }
+
+    /// Returns the reverted chain, if any.
+    ///
+    /// Returns `Some` for [`ChainReverted`] and [`ChainReorged`], `None`
+    /// for [`ChainCommitted`].
+    ///
+    /// [`ChainReverted`]: HostNotificationKind::ChainReverted
+    /// [`ChainReorged`]: HostNotificationKind::ChainReorged
+    /// [`ChainCommitted`]: HostNotificationKind::ChainCommitted
+    pub const fn reverted_chain(&self) -> Option<&Arc<C>> {
+        match self {
+            Self::ChainReverted { old } | Self::ChainReorged { old, .. } => Some(old),
+            Self::ChainCommitted { .. } => None,
+        }
+    }
+}

crates/node-types/src/notifier.rs

@@ -0,0 +1,56 @@
+use crate::HostNotification;
+use core::future::Future;
+use signet_extract::Extractable;
+
+/// Abstraction over a host chain notification source.
+///
+/// Drives the signet node's main loop: yielding chain events, controlling
+/// backfill, and sending feedback. All block data comes from notifications;
+/// the backend handles hash resolution internally.
+///
+/// # Implementors
+///
+/// - `signet-host-reth`: wraps reth's `ExExContext`
+///
+/// # Implementing
+///
+/// Implementations must uphold the following contract:
+///
+/// 1. **`set_head`** — called once at startup before the first
+///    [`next_notification`]. The backend must resolve the block number to a
+///    hash (falling back to genesis if the number is not yet available) and
+///    begin delivering notifications from that point.
+/// 2. **`next_notification`** — must yield notifications in host-chain order.
+///    Returning `None` signals a clean shutdown.
+/// 3. **`set_backfill_thresholds`** — may be called at any time. Passing
+///    `None` should restore the backend's default batch size.
+/// 4. **`send_finished_height`** — may be called after processing each
+///    notification batch. The backend resolves the block number to a hash
+///    internally. Sending a height that has already been acknowledged is a
+///    no-op.
+///
+/// [`next_notification`]: HostNotifier::next_notification
+pub trait HostNotifier {
+    /// A chain segment — contiguous blocks with receipts.
+    type Chain: Extractable;
+
+    /// The error type for fallible operations.
+    type Error: core::error::Error + Send + Sync + 'static;
+
+    /// Yield the next notification. `None` signals host shutdown.
+    fn next_notification(
+        &mut self,
+    ) -> impl Future<Output = Option<Result<HostNotification<Self::Chain>, Self::Error>>> + Send;
+
+    /// Set the head position, requesting backfill from this block number.
+    /// The backend resolves the block number to a block hash internally.
+    fn set_head(&mut self, block_number: u64);
+
+    /// Configure backfill batch size limits. `None` means use the backend's
+    /// default.
+    fn set_backfill_thresholds(&mut self, max_blocks: Option<u64>);
+
+    /// Signal that processing is complete up to this host block number.
+    /// The backend resolves the block number to a block hash internally.
+    fn send_finished_height(&self, block_number: u64) -> Result<(), Self::Error>;
+}

crates/node/Cargo.toml

@@ -9,31 +9,24 @@ homepage.workspace = true
 repository.workspace = true
 
 [dependencies]
+signet-blobber.workspace = true
 signet-block-processor.workspace = true
 signet-cold.workspace = true
 signet-evm.workspace = true
 signet-extract.workspace = true
 signet-genesis.workspace = true
+signet-hot.workspace = true
 signet-node-config.workspace = true
+signet-node-types.workspace = true
 signet-rpc.workspace = true
-signet-hot.workspace = true
 signet-storage.workspace = true
-
-signet-blobber.workspace = true
 signet-tx-cache.workspace = true
 signet-types.workspace = true
 
 alloy.workspace = true
-
-reth.workspace = true
-reth-exex.workspace = true
-reth-node-api.workspace = true
-reth-stages-types.workspace = true
-
 trevm.workspace = true
 
 eyre.workspace = true
-futures-util.workspace = true
 metrics.workspace = true
 reqwest.workspace = true
 tokio.workspace = true