feat(payload): make the actual payload build function generic (#4153)

crates/payload/basic/src/lib.rs

@@ -312,12 +312,15 @@ where
                     // acquire the permit for executing the task
                     let _permit = guard.0.acquire().await;
                     build_payload(
+                        default_payload_builder,
+                        BuildArguments {
                             client,
                             pool,
                             cached_reads,
-                        payload_config,
+                            config: payload_config,
                             cancel,
                             best_payload,
+                        },
                         tx,
                     )
                 }));
@@ -516,8 +519,9 @@ struct PayloadConfig {
     chain_spec: Arc<ChainSpec>,
 }
 
+/// The possible outcomes of a payload building attempt.
 #[derive(Debug)]
-enum BuildOutcome {
+pub enum BuildOutcome {
     /// Successfully built a better block.
     Better {
         /// The new payload that was built.
@@ -527,6 +531,7 @@ enum BuildOutcome {
     },
     /// Aborted payload building because resulted in worse block wrt. fees.
     Aborted {
+        /// The total fees associated with the attempted payload.
         fees: U256,
         /// The cached reads that were used to build the payload.
         cached_reads: CachedReads,
@@ -535,32 +540,73 @@ enum BuildOutcome {
     Cancelled,
 }
 
-/// Builds the payload and sends the result to the given channel.
+/// A collection of arguments used for building payloads.
-fn build_payload<Pool, Client>(
+///
+/// This struct encapsulates the essential components and configuration required for the payload
+/// building process. It holds references to the Ethereum client, transaction pool, cached reads,
+/// payload configuration, cancellation status, and the best payload achieved so far.
+pub struct BuildArguments<Pool, Client> {
     client: Client,
     pool: Pool,
     cached_reads: CachedReads,
     config: PayloadConfig,
     cancel: Cancelled,
     best_payload: Option<Arc<BuiltPayload>>,
-    to_job: oneshot::Sender<Result<BuildOutcome, PayloadBuilderError>>,
+}
-) where
+
+/// A trait for building payloads that encapsulate Ethereum transactions.
+///
+/// This trait provides the `try_build` method to construct a transaction payload
+/// using `BuildArguments`. It returns a `Result` indicating success or a
+/// `PayloadBuilderError` if building fails.
+///
+/// Generic parameters `Pool` and `Client` represent the transaction pool and
+/// Ethereum client types.
+pub trait PayloadBuilder<Pool, Client> {
+    /// Tries to build a transaction payload using provided arguments.
+    ///
+    /// Constructs a transaction payload based on the given arguments,
+    /// returning a `Result` indicating success or an error if building fails.
+    ///
+    /// # Arguments
+    ///
+    /// - `args`: Build arguments containing necessary components.
+    ///
+    /// # Returns
+    ///
+    /// A `Result` indicating the build outcome or an error.
+    fn try_build(
+        &self,
+        args: BuildArguments<Pool, Client>,
+    ) -> Result<BuildOutcome, PayloadBuilderError>;
+}
+
+impl<Pool, Client, F> PayloadBuilder<Pool, Client> for F
+where
+    F: Fn(BuildArguments<Pool, Client>) -> Result<BuildOutcome, PayloadBuilderError>,
+{
+    fn try_build(
+        &self,
+        args: BuildArguments<Pool, Client>,
+    ) -> Result<BuildOutcome, PayloadBuilderError> {
+        self(args)
+    }
+}
+
+/// Constructs an Ethereum transaction payload using the best transactions from the pool.
+///
+/// Given build arguments including an Ethereum client, transaction pool,
+/// and configuration, this function creates a transaction payload. Returns
+/// a result indicating success with the payload or an error in case of failure.
+fn default_payload_builder<Pool, Client>(
+    args: BuildArguments<Pool, Client>,
+) -> Result<BuildOutcome, PayloadBuilderError>
+where
     Client: StateProviderFactory,
     Pool: TransactionPool,
 {
-    #[inline(always)]
+    let BuildArguments { client, pool, mut cached_reads, config, cancel, best_payload } = args;
-    fn try_build<Pool, Client>(
+
-        client: Client,
-        pool: Pool,
-        mut cached_reads: CachedReads,
-        config: PayloadConfig,
-        cancel: Cancelled,
-        best_payload: Option<Arc<BuiltPayload>>,
-    ) -> Result<BuildOutcome, PayloadBuilderError>
-    where
-        Client: StateProviderFactory,
-        Pool: TransactionPool,
-    {
     let PayloadConfig {
         initialized_block_env,
         initialized_cfg,
@@ -626,11 +672,7 @@ fn build_payload<Pool, Client>(
                         } else {
                             // if the transaction is invalid, we can skip it and all of its
                             // descendants
-                                trace!(
+                            trace!(?err, ?tx, "skipping invalid transaction and its descendants");
-                                    ?err,
-                                    ?tx,
-                                    "skipping invalid transaction and its descendants"
-                                );
                             best_txs.mark_invalid(&pool_tx);
                         }
                         continue
@@ -663,9 +705,8 @@ fn build_payload<Pool, Client>(
         );
 
         // update add to total fees
-            let miner_fee = tx
+        let miner_fee =
-                .effective_tip_per_gas(base_fee)
+            tx.effective_tip_per_gas(base_fee).expect("fee is always valid; execution succeeded");
-                .expect("fee is always valid; execution succeeded");
         total_fees += U256::from(miner_fee) * U256::from(gas_used);
 
         // append transaction to the list of executed transactions
@@ -726,8 +767,18 @@ fn build_payload<Pool, Client>(
         payload: BuiltPayload::new(attributes.id, sealed_block, total_fees),
         cached_reads,
     })
-    }
+}
-    let _ = to_job.send(try_build(client, pool, cached_reads, config, cancel, best_payload));
+
+fn build_payload<Pool, Client>(
+    builder: impl PayloadBuilder<Pool, Client>,
+    args: BuildArguments<Pool, Client>,
+    to_job: oneshot::Sender<Result<BuildOutcome, PayloadBuilderError>>,
+) where
+    Client: StateProviderFactory,
+    Pool: TransactionPool,
+{
+    let result = builder.try_build(args);
+    let _ = to_job.send(result);
 }
 
 /// Builds an empty payload without any transactions.