chore: move engine-primitives to engine folder (#9130)

crates/engine/primitives/Cargo.toml

@@ -0,0 +1,19 @@
+[package]
+name = "reth-engine-primitives"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+homepage.workspace = true
+repository.workspace = true
+
+[lints]
+workspace = true
+
+[dependencies]
+# reth
+reth-chainspec.workspace = true
+reth-payload-primitives.workspace = true
+
+# misc
+serde.workspace = true

crates/engine/primitives/src/error.rs

@@ -0,0 +1,65 @@
+//! Defines a payload validation error type
+use thiserror::Error;
+
+/// Thrown when the payload or attributes are known to be invalid before processing.
+///
+/// This is used mainly for
+/// [`validate_version_specific_fields`](crate::validate_version_specific_fields), which validates
+/// both execution payloads and forkchoice update attributes with respect to a method version.
+#[derive(Error, Debug)]
+pub enum EngineObjectValidationError {
+    /// Thrown when the underlying validation error occurred while validating an
+    /// `ExecutionPayload`.
+    #[error("Payload validation error: {0}")]
+    Payload(VersionSpecificValidationError),
+
+    /// Thrown when the underlying validation error occurred while validating a
+    /// `PayloadAttributes`.
+    #[error("Payload attributes validation error: {0}")]
+    PayloadAttributes(VersionSpecificValidationError),
+
+    /// Thrown if `PayloadAttributes` or `ExecutionPayload` were provided with a timestamp, but the
+    /// version of the engine method called is meant for a fork that occurs after the provided
+    /// timestamp.
+    #[error("Unsupported fork")]
+    UnsupportedFork,
+    /// Another type of error that is not covered by the above variants.
+    #[error("Invalid params: {0}")]
+    InvalidParams(#[from] Box<dyn std::error::Error + Send + Sync>),
+}
+
+/// Thrown when validating an execution payload OR payload attributes fails due to:
+/// * The existence of a new field that is not supported in the given engine method version, or
+/// * The absence of a field that is required in the given engine method version
+#[derive(Error, Debug)]
+pub enum VersionSpecificValidationError {
+    /// Thrown if the pre-V3 `PayloadAttributes` or `ExecutionPayload` contains a parent beacon
+    /// block root
+    #[error("parent beacon block root not supported before V3")]
+    ParentBeaconBlockRootNotSupportedBeforeV3,
+    /// Thrown if `engine_forkchoiceUpdatedV1` or `engine_newPayloadV1` contains withdrawals
+    #[error("withdrawals not supported in V1")]
+    WithdrawalsNotSupportedInV1,
+    /// Thrown if `engine_forkchoiceUpdated` or `engine_newPayload` contains no withdrawals after
+    /// Shanghai
+    #[error("no withdrawals post-Shanghai")]
+    NoWithdrawalsPostShanghai,
+    /// Thrown if `engine_forkchoiceUpdated` or `engine_newPayload` contains withdrawals before
+    /// Shanghai
+    #[error("withdrawals pre-Shanghai")]
+    HasWithdrawalsPreShanghai,
+    /// Thrown if the `PayloadAttributes` or `ExecutionPayload` contains no parent beacon block
+    /// root after Cancun
+    #[error("no parent beacon block root post-cancun")]
+    NoParentBeaconBlockRootPostCancun,
+}
+
+impl EngineObjectValidationError {
+    /// Creates an instance of the `InvalidParams` variant with the given error.
+    pub fn invalid_params<E>(error: E) -> Self
+    where
+        E: std::error::Error + Send + Sync + 'static,
+    {
+        Self::InvalidParams(Box::new(error))
+    }
+}

crates/engine/primitives/src/lib.rs

@@ -0,0 +1,47 @@
+//! Traits, validation methods, and helper types used to abstract over engine types.
+
+#![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",
+    issue_tracker_base_url = "https://github.com/paradigmxyz/reth/issues/"
+)]
+#![cfg_attr(not(test), warn(unused_crate_dependencies))]
+#![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]
+
+use reth_chainspec::ChainSpec;
+pub use reth_payload_primitives::{
+    BuiltPayload, EngineApiMessageVersion, EngineObjectValidationError, PayloadOrAttributes,
+    PayloadTypes,
+};
+use serde::{de::DeserializeOwned, ser::Serialize};
+
+/// This type defines the versioned types of the engine API.
+///
+/// This includes the execution payload types and payload attributes that are used to trigger a
+/// payload job. Hence this trait is also [`PayloadTypes`].
+pub trait EngineTypes:
+    PayloadTypes<
+        BuiltPayload: TryInto<Self::ExecutionPayloadV1>
+                          + TryInto<Self::ExecutionPayloadV2>
+                          + TryInto<Self::ExecutionPayloadV3>
+                          + TryInto<Self::ExecutionPayloadV4>,
+    > + DeserializeOwned
+    + Serialize
+{
+    /// Execution Payload V1 type.
+    type ExecutionPayloadV1: DeserializeOwned + Serialize + Clone + Unpin + Send + Sync + 'static;
+    /// Execution Payload V2 type.
+    type ExecutionPayloadV2: DeserializeOwned + Serialize + Clone + Unpin + Send + Sync + 'static;
+    /// Execution Payload V3 type.
+    type ExecutionPayloadV3: DeserializeOwned + Serialize + Clone + Unpin + Send + Sync + 'static;
+    /// Execution Payload V4 type.
+    type ExecutionPayloadV4: DeserializeOwned + Serialize + Clone + Unpin + Send + Sync + 'static;
+
+    /// Validates the presence or exclusion of fork-specific fields based on the payload attributes
+    /// and the message version.
+    fn validate_version_specific_fields(
+        chain_spec: &ChainSpec,
+        version: EngineApiMessageVersion,
+        payload_or_attrs: PayloadOrAttributes<'_, Self::PayloadAttributes>,
+    ) -> Result<(), EngineObjectValidationError>;
+}