Merge pull request #9 from sigp/mev-bundle-types

Author: realbigsean

Cargo.toml

@@ -9,6 +9,8 @@ members = [
   "relay-api-types",
   "relay-client",
   "relay-server",
+  "searcher-api-types",
+  "searcher-client",
   "common"
 ]
 
@@ -27,7 +29,7 @@ reqwest = { version = "0.12.5", features = ["json"] }
 serde = { version = "1.0", features = ["derive"] }
 serde_json = { version = "1", features = ["raw_value"] }
 superstruct = "0.8"
-tokio = { version = "1", default-features = false, features = ["signal", "rt-multi-thread"] }
+tokio = { version = "1", default-features = false, features = ["signal", "rt-multi-thread", "macros"] }
 tokio-tungstenite = "0.24.0"
 tracing = { version = "0.1", features = ["attributes"] }
 types = { git = "https://github.com/sigp/lighthouse.git", rev = "c33307d70287fd3b7a70785f89dadcb737214903" }

searcher-api-types/Cargo.toml

@@ -0,0 +1,14 @@
+[package]
+name = "searcher-api-types"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+serde = { workspace = true }
+serde_json = { workspace = true }
+
+alloy-primitives = "0.8"
+alloy-rlp = "0.3"
+alloy-rpc-types-mev = "0.8"
+eyre = "0.6.12"
+serde_with = "3.12.0"

searcher-api-types/src/beaver.rs

@@ -0,0 +1,89 @@
+//! RPC types that are supported by Beaverbuild
+use alloy_primitives::{hex::FromHex, Address, BlockNumber, Bytes, TxHash};
+use alloy_rpc_types_mev::EthSendBundle;
+use serde::Serialize;
+use serde_with::{serde_as, skip_serializing_none};
+
+/// Bundle as recognised by Beaverbuild
+///
+/// Consult <https://beaverbuild.org/docs.html>. Note that the deprecated `replacementUuid` field
+/// has been omitted.
+#[serde_as]
+#[skip_serializing_none]
+#[derive(Clone, Debug, Default, Serialize)]
+pub struct BeaverBundle {
+    #[serde(flatten)]
+    pub bundle: EthSendBundle,
+    #[serde(skip_serializing_if = "Vec::is_empty")]
+    /// A list of transaction hashes contained in the bundle, that can be allowed to be removed from your bundle if it's deemed useful (but not revert)
+    pub dropping_transaction_hashes: Vec<TxHash>,
+    /// An integer between 1-99. How much of the total priority fee + coinbase payment you want to be refunded for. This will negatively impact your prioritization because this refund is gonna eat into your bundle payment. Example: if a bundle pays 0.2 ETH of priority fee plus 1 ETH to coinbase, a refundPercent set to 50 will result in a transaction being appended after the bundle, paying 0.59 ETH back to the EOA. This is assuming the payout tx will cost beaver 0.01 ETH in fees, which are deduced from the 0.6 ETH payout.
+    pub refund_percent: Option<u64>,
+    /// You can specify an address that the funds from `refundPercent` will be sent to. If not specified, they will be sent to the `from` address of the first transaction
+    pub refund_recipient: Option<Address>,
+    #[serde(skip_serializing_if = "Vec::is_empty")]
+    /// The hashes of transactions in the bundle that the refund will be based on. If it's empty, we'll use the last transaction
+    pub refund_transaction_hashes: Vec<TxHash>,
+}
+
+pub fn bundle_from_rlp_hex(
+    txs: Vec<String>,
+    block_number: BlockNumber,
+) -> eyre::Result<EthSendBundle> {
+    Ok(EthSendBundle {
+        txs: txs
+            .iter()
+            .map(Bytes::from_hex)
+            .collect::<Result<Vec<Bytes>, _>>()?,
+        block_number,
+        ..EthSendBundle::default()
+    })
+}
+
+#[cfg(test)]
+mod test {
+    use super::*;
+
+    #[test]
+    fn test_beaver_bundle_serialisation() {
+        assert!(serde_json::to_string(&BeaverBundle::default()).is_ok());
+        assert_eq!(
+            serde_json::to_string(&BeaverBundle::default()).unwrap(),
+            "{\"txs\":[],\"blockNumber\":\"0x0\"}".to_string()
+        );
+
+        assert!(serde_json::to_string(&BeaverBundle {
+            bundle: EthSendBundle {
+                txs: vec![],
+                block_number: 21862873,
+                ..Default::default()
+            },
+            ..Default::default()
+        })
+        .is_ok());
+        assert_eq!(
+            serde_json::to_string(&BeaverBundle {
+                bundle: EthSendBundle {
+                    txs: vec![],
+                    block_number: 21862873,
+                    ..Default::default()
+                },
+                ..Default::default()
+            })
+            .unwrap(),
+            "{\"txs\":[],\"blockNumber\":\"0x14d99d9\"}".to_string()
+        );
+        assert!(
+            serde_json::to_string(&
+                bundle_from_rlp_hex(vec!["0x02f8b20181948449bdee618501dcd6500083016b93942dabcea55a12d73191aece59f508b191fb68adac80b844095ea7b300000000000000000000000054e44dbb92dba848ace27f44c0cb4268981ef1cc00000000000000000000000000000000000000000000000052616e065f6915ebc080a0c497b6e53d7cb78e68c37f6186c8bb9e1b8a55c3e22462163495979b25c2caafa052769811779f438b73159c4cc6a05a889da8c1a16e432c2e37e3415c9a0b9887".to_string()], 21862873).unwrap()
+        )
+        .is_ok());
+        assert_eq!(
+            serde_json::to_string(&
+                bundle_from_rlp_hex(vec!["0x02f8b20181948449bdee618501dcd6500083016b93942dabcea55a12d73191aece59f508b191fb68adac80b844095ea7b300000000000000000000000054e44dbb92dba848ace27f44c0cb4268981ef1cc00000000000000000000000000000000000000000000000052616e065f6915ebc080a0c497b6e53d7cb78e68c37f6186c8bb9e1b8a55c3e22462163495979b25c2caafa052769811779f438b73159c4cc6a05a889da8c1a16e432c2e37e3415c9a0b9887".to_string()], 21862873).unwrap()
+        )
+            .unwrap(),
+            "{\"txs\":[\"0x02f8b20181948449bdee618501dcd6500083016b93942dabcea55a12d73191aece59f508b191fb68adac80b844095ea7b300000000000000000000000054e44dbb92dba848ace27f44c0cb4268981ef1cc00000000000000000000000000000000000000000000000052616e065f6915ebc080a0c497b6e53d7cb78e68c37f6186c8bb9e1b8a55c3e22462163495979b25c2caafa052769811779f438b73159c4cc6a05a889da8c1a16e432c2e37e3415c9a0b9887\"],\"blockNumber\":\"0x14d99d9\"}".to_string()
+        );
+    }
+}

searcher-api-types/src/flashbots.rs

@@ -0,0 +1,3 @@
+use alloy_rpc_types_mev::EthSendBundle;
+
+pub type FlashbotsBundle = EthSendBundle;

searcher-api-types/src/lib.rs

@@ -0,0 +1,77 @@
+use alloy_primitives::{BlockNumber, Bytes, TxHash};
+use alloy_rlp::encode;
+use serde::Serialize;
+
+pub mod beaver;
+pub mod flashbots;
+pub mod titan;
+
+pub use beaver::*;
+pub use flashbots::*;
+pub use titan::*;
+
+/// Universal bundle submission RPC type
+///
+/// This type represents what Lynx accepts from external order flow providers.
+#[derive(Clone, Debug, Serialize)]
+#[serde(untagged)]
+pub enum SendBundleRequest {
+    /// Flashbots bundle
+    Flashbots(FlashbotsBundle),
+    /// Beaverbuild bundle
+    Beaver(BeaverBundle),
+    /// Titan Builder bundle
+    Titan(TitanBundle),
+}
+
+impl SendBundleRequest {
+    pub fn min_timestamp(&self) -> Option<u64> {
+        match self {
+            SendBundleRequest::Flashbots(bundle) => bundle.min_timestamp,
+            SendBundleRequest::Beaver(bundle) => bundle.bundle.min_timestamp,
+            SendBundleRequest::Titan(bundle) => bundle.bundle.min_timestamp,
+        }
+    }
+
+    pub fn max_timestamp(&self) -> Option<u64> {
+        match self {
+            SendBundleRequest::Flashbots(bundle) => bundle.max_timestamp,
+            SendBundleRequest::Beaver(bundle) => bundle.bundle.max_timestamp,
+            SendBundleRequest::Titan(bundle) => bundle.bundle.max_timestamp,
+        }
+    }
+
+    pub fn block_number(&self) -> BlockNumber {
+        match self {
+            SendBundleRequest::Flashbots(bundle) => bundle.block_number,
+            SendBundleRequest::Beaver(bundle) => bundle.bundle.block_number,
+            SendBundleRequest::Titan(bundle) => bundle.bundle.block_number,
+        }
+    }
+
+    pub fn tx_bytes(&self) -> Vec<Bytes> {
+        match self {
+            SendBundleRequest::Flashbots(bundle) => bundle.txs.clone(),
+            SendBundleRequest::Beaver(bundle) => bundle
+                .bundle
+                .txs
+                .iter()
+                .map(|tx| encode(tx).into())
+                .collect(),
+            SendBundleRequest::Titan(bundle) => bundle
+                .bundle
+                .txs
+                .iter()
+                .map(|tx| encode(tx).into())
+                .collect(),
+        }
+    }
+
+    pub fn reverting_tx_hashes(&self) -> Vec<TxHash> {
+        match self {
+            SendBundleRequest::Flashbots(_) => vec![],
+            SendBundleRequest::Beaver(bundle) => bundle.bundle.reverting_tx_hashes.clone(),
+            SendBundleRequest::Titan(bundle) => bundle.bundle.reverting_tx_hashes.clone(),
+        }
+    }
+}

searcher-api-types/src/titan.rs

@@ -0,0 +1,3 @@
+use crate::beaver::BeaverBundle;
+
+pub type TitanBundle = BeaverBundle;

searcher-client/Cargo.toml

@@ -0,0 +1,16 @@
+[package]
+name = "searcher-client"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+tokio = { workspace = true }
+
+alloy-rpc-types-mev = "0.8"
+eyre = "0.6.12"
+url = "2.5.4"
+jsonrpsee = { version = "0.24.8", features = ["jsonrpsee-http-client", "jsonrpsee-core"] }
+
+searcher-api-types = { path = "../searcher-api-types" }
+jsonrpsee-core = "0.24.8"
+

searcher-client/src/lib.rs

@@ -0,0 +1,56 @@
+use alloy_rpc_types_mev::EthBundleHash;
+use jsonrpsee::http_client::HttpClient;
+use jsonrpsee::rpc_params;
+use jsonrpsee_core::client::ClientT;
+use url::Url;
+
+use searcher_api_types::SendBundleRequest;
+
+pub async fn send_bundle(url: Url, bundle: &SendBundleRequest) -> eyre::Result<EthBundleHash> {
+    Ok(HttpClient::builder()
+        .build(url)?
+        .request("eth_sendBundle", rpc_params![bundle])
+        .await?)
+}
+
+#[cfg(test)]
+mod test {
+    use super::*;
+
+    use alloy_rpc_types_mev::EthSendBundle;
+    use searcher_api_types::{bundle_from_rlp_hex, BeaverBundle, SendBundleRequest};
+
+    const TEST_ENDPOINT: &str = "https://rpc.beaverbuild.org";
+
+    fn test_endpoint() -> Url {
+        TEST_ENDPOINT.parse().unwrap()
+    }
+
+    #[tokio::test]
+    async fn test_send_bundle_beaver_rejects_empty_bundle() {
+        let empty_bundle = SendBundleRequest::Beaver(BeaverBundle {
+            bundle: EthSendBundle {
+                txs: vec![],
+                block_number: 0,
+                ..EthSendBundle::default()
+            },
+            ..BeaverBundle::default()
+        });
+        let res = send_bundle(test_endpoint(), &empty_bundle).await;
+        assert!(res.is_err());
+    }
+
+    #[tokio::test]
+    async fn test_send_bundle_beaver_success() {
+        let bundle = SendBundleRequest::Beaver(
+            BeaverBundle { bundle: bundle_from_rlp_hex(vec!["0x02f8b20181948449bdee618501dcd6500083016b93942dabcea55a12d73191aece59f508b191fb68adac80b844095ea7b300000000000000000000000054e44dbb92dba848ace27f44c0cb4268981ef1cc00000000000000000000000000000000000000000000000052616e065f6915ebc080a0c497b6e53d7cb78e68c37f6186c8bb9e1b8a55c3e22462163495979b25c2caafa052769811779f438b73159c4cc6a05a889da8c1a16e432c2e37e3415c9a0b9887".to_string()], 1).expect("illegal RLP bytes for bundle"), ..BeaverBundle::default()}
+        );
+        let res = send_bundle(test_endpoint(), &bundle).await;
+        assert!(res.is_ok());
+        let resp = res.unwrap();
+        assert_eq!(
+            resp.bundle_hash.to_string(),
+            "0xbfe05fa7cb2f9de981eeefe7246c9c9be6f69c3a3b33a05fdbf6afac42ddd294"
+        );
+    }
+}