wip: adds Flashbots provider

- adds a FlashbotsProvider for interacting with Flashbots API
- adds smoke tests for sim and send bundle Flashbots endpoints
- adds a make target for running the Flashbots integration tests

Author: dylanlott

Cargo.lock

@@ -23,6 +23,7 @@ integration = []
 [dependencies]
 init4-bin-base = { version = "0.10.1", features = ["perms"] }
 
+signet-bundle = { version = "0.9.0" }
 signet-constants = { version = "0.9.0" }
 signet-sim = { version = "0.9.0" }
 signet-tx-cache = { version = "0.9.0" }
@@ -39,8 +40,9 @@ alloy = { version = "1.0.19", features = [
     "rlp",
     "node-bindings",
     "serde",
-    "getrandom"
+    "getrandom",
 ] }
+alloy-transport = "1.0.19"
 
 serde = { version = "1.0.197", features = ["derive"] }
 
@@ -55,3 +57,4 @@ chrono = "0.4.40"
 tokio-stream = "0.1.17"
 url = "2.5.4"
 tracing = "0.1.41"
+async-trait = "0.1.88"

Cargo.toml

@@ -43,5 +43,8 @@ fmt:
 clippy:
 	$(CARGO) clippy $(CLIPPY_FLAGS)
 
+test-flashbots:
+	$(CARGO) test --test flashbots_provider_test -- --ignored
+
 tx-submitter:
 	$(CARGO) run --bin transaction-submitter

Makefile

@@ -0,0 +1,16 @@
+//! Signet's Flashbots Block Submitter
+
+/// handles rollup block submission to the Flashbots network
+/// via the provider
+pub mod submitter;
+pub use submitter::FlashbotsSubmitter;
+
+/// implements a bundle provider API for building Flashbots
+/// compatible MEV bundles
+pub mod provider;
+pub use provider::FlashbotsProvider;
+
+/// handles the lifecyle of receiving, preparing, and submitting
+/// a rollup block to the Flashbots network.
+pub mod task;
+pub use task::FlashbotsTask;

src/tasks/submit/flashbots/mod.rs

@@ -0,0 +1,143 @@
+//! A generic Flashbots bundle API wrapper.
+use alloy::network::{Ethereum, Network};
+use alloy::primitives::Address;
+use alloy::providers::{
+    Provider, SendableTx,
+    fillers::{FillerControlFlow, TxFiller},
+};
+use alloy::rpc::types::eth::TransactionRequest;
+use alloy::rpc::types::mev::{EthBundleHash, MevSendBundle, ProtocolVersion};
+use alloy_transport::TransportResult;
+use eyre::Context as _;
+use std::ops::Deref;
+
+use crate::tasks::block::sim::SimResult;
+use signet_types::SignedFill;
+
+/// A wrapper over a `Provider` that adds Flashbots MEV bundle helpers.
+#[derive(Debug, Clone)]
+pub struct FlashbotsProvider<P> {
+    inner: P,
+    /// The base URL for the Flashbots API.
+    pub relay_url: url::Url,
+}
+
+impl<P: Provider<Ethereum>> FlashbotsProvider<P> {
+    /// Wraps a provider with the URL and returns a new `FlashbotsProvider`.
+    pub fn new(inner: P, relay_url: url::Url) -> Self {
+        Self { inner, relay_url }
+    }
+
+    /// Consume self and return the inner provider.
+    pub fn into_inner(self) -> P {
+        self.inner
+    }
+
+    /// Borrow the inner provider.
+    pub const fn inner(&self) -> &P {
+        &self.inner
+    }
+}
+
+impl<P> Deref for FlashbotsProvider<P> {
+    type Target = P;
+    fn deref(&self) -> &Self::Target {
+        &self.inner
+    }
+}
+
+impl<P> FlashbotsProvider<P>
+where
+    P: Provider<Ethereum> + Clone + Send + Sync + 'static,
+{
+    /// Convert a SignedFill to a TransactionRequest calling the Orders contract.
+    ///
+    /// This prepares the calldata for RollupOrders::fillPermit2(outputs, permit2) and sets
+    /// `to` to the given Orders contract address. The returned request is unsigned.
+    pub fn fill_to_tx_request(fill: &SignedFill, orders_contract: Address) -> TransactionRequest {
+        fill.to_fill_tx(orders_contract)
+    }
+
+    /// Construct a new empty bundle template for the given block number.
+    pub fn empty_bundle(&self, target_block: u64) -> MevSendBundle {
+        MevSendBundle::new(target_block, Some(target_block), ProtocolVersion::V0_1, vec![])
+    }
+
+    /// Prepares a bundle transaction from the simulation result.
+    pub fn prepare_bundle(&self, sim_result: &SimResult, target_block: u64) -> MevSendBundle {
+        let bundle_body = Vec::new();
+
+        // Populate the bundle body with the simulation result.
+
+        // TODO: Push host fills into the Flashbots bundle body.
+        let _host_fills = sim_result.block.host_fills();
+        // _host_fills.iter().map(|f| f.to_fill_tx(todo!()));
+
+        // TODO: Add the rollup block blob transaction to the Flashbots bundle body.
+        // let blob_tx = ...;
+        let _ = &sim_result; // keep param used until wired
+
+        // Create the bundle from the target block and bundle body
+        MevSendBundle::new(target_block, Some(target_block), ProtocolVersion::V0_1, bundle_body)
+    }
+
+    /// Submit the prepared Flashbots bundle to the relay via `mev_sendBundle`.
+    pub async fn send_bundle(&self, bundle: MevSendBundle) -> eyre::Result<EthBundleHash> {
+        // NOTE: The Flashbots relay expects a single parameter which is the bundle object.
+        // Alloy's `raw_request` accepts any serializable params; wrapping in a 1-tuple is fine.
+        let hash: EthBundleHash = self
+            .inner
+            .raw_request("mev_sendBundle".into(), (bundle,))
+            .await
+            .wrap_err("flashbots mev_sendBundle RPC failed")?;
+        Ok(hash)
+    }
+
+    /// Simulate a bundle via `mev_simBundle`.
+    pub async fn simulate_bundle(&self, bundle: &MevSendBundle) -> eyre::Result<()> {
+        // We ignore the response (likely a JSON object with sim traces) for now and just ensure success.
+        let _resp: serde_json::Value = self
+            .inner
+            .raw_request("mev_simBundle".into(), (bundle.clone(),))
+            .await
+            .wrap_err("flashbots mev_simBundle RPC failed")?;
+        Ok(())
+    }
+
+    /// Check the status of a previously submitted bundle.
+    pub async fn bundle_status(&self, _hash: EthBundleHash) -> eyre::Result<()> {
+        eyre::bail!("FlashbotsProvider::bundle_status unimplemented")
+    }
+}
+
+impl<N, P> TxFiller<N> for FlashbotsProvider<P>
+where
+    N: Network,
+    P: TxFiller<N> + Provider<N> + Clone + Send + Sync + core::fmt::Debug + 'static,
+{
+    type Fillable = <P as TxFiller<N>>::Fillable;
+
+    fn status(&self, tx: &N::TransactionRequest) -> FillerControlFlow {
+        TxFiller::<N>::status(&self.inner, tx)
+    }
+
+    fn fill_sync(&self, tx: &mut SendableTx<N>) {
+        TxFiller::<N>::fill_sync(&self.inner, tx)
+    }
+
+    fn prepare<Prov: Provider<N>>(
+        &self,
+        provider: &Prov,
+        tx: &N::TransactionRequest,
+    ) -> impl core::future::Future<Output = TransportResult<Self::Fillable>> + Send {
+        TxFiller::<N>::prepare(&self.inner, provider, tx)
+    }
+
+    fn fill(
+        &self,
+        fillable: Self::Fillable,
+        tx: SendableTx<N>,
+    ) -> impl core::future::Future<Output = TransportResult<SendableTx<N>>> + Send {
+        TxFiller::<N>::fill(&self.inner, fillable, tx)
+    }
+}

src/tasks/submit/flashbots/provider.rs

@@ -0,0 +1,94 @@
+//! Flashbots Task receives simulated blocks from an upstream channel and
+//! submits them to the Flashbots relay as bundles.
+use crate::{
+    quincey::Quincey,
+    tasks::{block::sim::SimResult, submit::flashbots::FlashbotsProvider},
+};
+use alloy::{network::Ethereum, primitives::TxHash, providers::Provider};
+use init4_bin_base::deps::tracing::{debug, error};
+use signet_constants::SignetSystemConstants;
+use tokio::{sync::mpsc, task::JoinHandle};
+
+/// Handles construction, simulation, and submission of rollup blocks to the
+/// Flashbots network.
+#[derive(Debug)]
+pub struct FlashbotsTask<P> {
+    /// Builder configuration for the task.
+    pub config: crate::config::BuilderConfig,
+    /// System constants for the rollup and host chain.
+    pub constants: SignetSystemConstants,
+    /// Quincey instance for block signing.
+    pub quincey: Quincey,
+    /// Provider for interacting with  Flashbots API.
+    pub provider: P,
+    /// Channel for sending hashes of outbound transactions.
+    pub outbound: mpsc::UnboundedSender<TxHash>,
+}
+
+impl<P> FlashbotsTask<P>
+where
+    P: Provider<Ethereum> + Clone + Send + Sync + 'static,
+{
+    /// Returns a new FlashbotsTask instance that receives `SimResult` types from the given
+    /// channel and handles their preparation, submission to the Flashbots network.
+    pub fn new(
+        config: crate::config::BuilderConfig,
+        constants: SignetSystemConstants,
+        quincey: Quincey,
+        provider: P,
+        outbound: mpsc::UnboundedSender<TxHash>,
+    ) -> FlashbotsTask<P> {
+        Self { config, constants, quincey, provider, outbound }
+    }
+
+    /// Task future that runs the Flashbots submission loop.
+    async fn task_future(self, mut inbound: mpsc::UnboundedReceiver<SimResult>) {
+        debug!("starting flashbots task");
+
+        // Wrap the underlying host provider with Flashbots helpers.
+        let flashbots =
+            FlashbotsProvider::new(self.provider, self.config.flashbots_endpoint.into());
+
+        loop {
+            let Some(sim_result) = inbound.recv().await else {
+                debug!("upstream task gone - exiting flashbots task");
+                break;
+            };
+            debug!(?sim_result.env.block_env.number, "simulation block received");
+
+            let current_block: u64 = sim_result.env.block_env.number.to::<u64>();
+            let target_block = current_block + 1;
+
+            // TODO: populate and prepare bundle from `SimResult` once `BundleProvider` is wired.
+            let bundle = flashbots.prepare_bundle(&sim_result, target_block);
+
+            // simulate then send the bundle
+            let sim_bundle_result = flashbots.simulate_bundle(&bundle).await;
+            match sim_bundle_result {
+                Ok(_) => {
+                    debug!("bundle simulation successful, ready to send");
+                    match flashbots.send_bundle(bundle).await {
+                        Ok(bundle_hash) => {
+                            debug!(?bundle_hash, "bundle successfully sent to Flashbots");
+                        }
+                        Err(err) => {
+                            error!(?err, "failed to send bundle to Flashbots");
+                            continue;
+                        }
+                    }
+                }
+                Err(err) => {
+                    error!(?err, "bundle simulation failed");
+                    continue;
+                }
+            }
+        }
+    }
+
+    /// Spawns the Flashbots task that handles incoming `SimResult`s.
+    pub fn spawn(self) -> (mpsc::UnboundedSender<SimResult>, JoinHandle<()>) {
+        let (sender, inbound) = mpsc::unbounded_channel::<SimResult>();
+        let handle = tokio::spawn(self.task_future(inbound));
+        (sender, handle)
+    }
+}

src/tasks/submit/flashbots/task.rs

@@ -4,5 +4,8 @@ pub use prep::{Bumpable, SubmitPrep};
 mod sim_err;
 pub use sim_err::{SimErrorResp, SimRevertKind};
 
-mod builder_helper;
+pub mod builder_helper;
 pub use builder_helper::{BuilderHelperTask, ControlFlow};
+
+pub mod flashbots;
+pub use flashbots::{FlashbotsSubmitter, FlashbotsTask};

src/tasks/submit/mod.rs

@@ -0,0 +1,78 @@
+//! Integration tests for the FlashbotsProvider.
+//! These tests require the `FLASHBOTS_ENDPOINT` env var to be set.
+#[cfg(test)]
+mod tests {
+    use alloy::{network::Ethereum, providers::ProviderBuilder};
+    use builder::tasks::submit::flashbots::FlashbotsProvider;
+
+    #[cfg(test)]
+    mod tests {
+        use super::*;
+        use alloy::{network::Ethereum, providers::ProviderBuilder};
+
+        #[tokio::test]
+        #[ignore = "integration test"]
+        async fn smoke_root_provider() {
+            let url: url::Url = "http://localhost:9062/".parse().unwrap();
+            let root = alloy::providers::RootProvider::<Ethereum>::new_http(url.clone());
+            let fill = ProviderBuilder::new_with_network().connect_provider(root);
+            let fp = FlashbotsProvider::new(fill, url);
+
+            assert_eq!(fp.relay_url.as_str(), "http://localhost:9062/");
+
+            let bundle = fp.empty_bundle(1);
+            let dbg_bundle = format!("{:?}", bundle);
+            assert!(dbg_bundle.contains("1"));
+        }
+
+        #[tokio::test]
+        #[ignore = "integration test"]
+        async fn smoke_simulate_bundle() {
+            let Ok(endpoint) = std::env::var("FLASHBOTS_ENDPOINT") else {
+                eprintln!("skipping: set FLASHBOTS_ENDPOINT to run integration test");
+                return;
+            };
+            let url: url::Url = endpoint.parse().expect("invalid FLASHBOTS_ENDPOINT");
+            let root = alloy::providers::RootProvider::<Ethereum>::new_http(url.clone());
+            let provider = ProviderBuilder::new_with_network().connect_provider(root);
+            let fp = FlashbotsProvider::new(provider, url);
+
+            let bundle = fp.empty_bundle(1);
+            let res = fp.simulate_bundle(&bundle).await;
+
+            if let Err(err) = &res {
+                eprintln!("simulate error (expected for empty bundle): {err}");
+            }
+
+            if let Err(err) = &res {
+                let msg = format!("{err}");
+                assert!(msg.contains("mev_simBundle"));
+            }
+
+            assert!(res.is_ok() || res.is_err());
+        }
+
+        #[tokio::test]
+        #[ignore = "integration test"]
+        async fn smoke_send_bundle() {
+            let Ok(endpoint) = std::env::var("FLASHBOTS_ENDPOINT") else {
+                eprintln!("skipping: set FLASHBOTS_ENDPOINT to run integration test");
+                return;
+            };
+            let url: url::Url = endpoint.parse().expect("invalid FLASHBOTS_ENDPOINT");
+            let root = alloy::providers::RootProvider::<Ethereum>::new_http(url.clone());
+            let provider = ProviderBuilder::new_with_network().connect_provider(root);
+            let fp = FlashbotsProvider::new(provider, url);
+
+            let bundle = fp.empty_bundle(1);
+            let res = fp.send_bundle(bundle).await;
+
+            if let Err(err) = &res {
+                let msg = format!("{err}");
+                assert!(msg.contains("mev_sendBundle"));
+            }
+
+            assert!(res.is_ok() || res.is_err());
+        }
+    }
+}