reth_payload_primitives/lib.rs
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374
//! This crate defines abstractions to create and update payloads (blocks)
#![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))]
mod error;
pub use error::{
EngineObjectValidationError, InvalidPayloadAttributesError, PayloadBuilderError,
VersionSpecificValidationError,
};
/// Contains traits to abstract over payload attributes types and default implementations of the
/// [`PayloadAttributes`] trait for ethereum mainnet and optimism types.
mod traits;
pub use traits::{
BuiltPayload, PayloadAttributes, PayloadAttributesBuilder, PayloadBuilderAttributes,
};
mod payload;
pub use payload::PayloadOrAttributes;
use reth_chainspec::EthereumHardforks;
/// The types that are used by the engine API.
pub trait PayloadTypes: Send + Sync + Unpin + core::fmt::Debug + Clone + 'static {
/// The built payload type.
type BuiltPayload: BuiltPayload + Clone + Unpin;
/// The RPC payload attributes type the CL node emits via the engine API.
type PayloadAttributes: PayloadAttributes + Unpin;
/// The payload attributes type that contains information about a running payload job.
type PayloadBuilderAttributes: PayloadBuilderAttributes<RpcPayloadAttributes = Self::PayloadAttributes>
+ Clone
+ Unpin;
}
/// Validates the timestamp depending on the version called:
///
/// * If V2, this ensures that the payload timestamp is pre-Cancun.
/// * If V3, this ensures that the payload timestamp is within the Cancun timestamp.
/// * If V4, this ensures that the payload timestamp is within the Prague timestamp.
///
/// Otherwise, this will return [`EngineObjectValidationError::UnsupportedFork`].
pub fn validate_payload_timestamp(
chain_spec: impl EthereumHardforks,
version: EngineApiMessageVersion,
timestamp: u64,
) -> Result<(), EngineObjectValidationError> {
let is_cancun = chain_spec.is_cancun_active_at_timestamp(timestamp);
if version == EngineApiMessageVersion::V2 && is_cancun {
// From the Engine API spec:
//
// ### Update the methods of previous forks
//
// This document defines how Cancun payload should be handled by the [`Shanghai
// API`](https://github.com/ethereum/execution-apis/blob/ff43500e653abde45aec0f545564abfb648317af/src/engine/shanghai.md).
//
// For the following methods:
//
// - [`engine_forkchoiceUpdatedV2`](https://github.com/ethereum/execution-apis/blob/ff43500e653abde45aec0f545564abfb648317af/src/engine/shanghai.md#engine_forkchoiceupdatedv2)
// - [`engine_newPayloadV2`](https://github.com/ethereum/execution-apis/blob/ff43500e653abde45aec0f545564abfb648317af/src/engine/shanghai.md#engine_newpayloadV2)
// - [`engine_getPayloadV2`](https://github.com/ethereum/execution-apis/blob/ff43500e653abde45aec0f545564abfb648317af/src/engine/shanghai.md#engine_getpayloadv2)
//
// a validation **MUST** be added:
//
// 1. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of
// payload or payloadAttributes is greater or equal to the Cancun activation timestamp.
return Err(EngineObjectValidationError::UnsupportedFork)
}
if version == EngineApiMessageVersion::V3 && !is_cancun {
// From the Engine API spec:
// <https://github.com/ethereum/execution-apis/blob/ff43500e653abde45aec0f545564abfb648317af/src/engine/cancun.md#specification-2>
//
// For `engine_getPayloadV3`:
//
// 1. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of
// the built payload does not fall within the time frame of the Cancun fork.
//
// For `engine_forkchoiceUpdatedV3`:
//
// 2. Client software **MUST** return `-38005: Unsupported fork` error if the
// `payloadAttributes` is set and the `payloadAttributes.timestamp` does not fall within
// the time frame of the Cancun fork.
//
// For `engine_newPayloadV3`:
//
// 2. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of
// the payload does not fall within the time frame of the Cancun fork.
return Err(EngineObjectValidationError::UnsupportedFork)
}
let is_prague = chain_spec.is_prague_active_at_timestamp(timestamp);
if version == EngineApiMessageVersion::V4 && !is_prague {
// From the Engine API spec:
// <https://github.com/ethereum/execution-apis/blob/7907424db935b93c2fe6a3c0faab943adebe8557/src/engine/prague.md#specification-1>
//
// For `engine_getPayloadV4`:
//
// 1. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of
// the built payload does not fall within the time frame of the Prague fork.
//
// For `engine_forkchoiceUpdatedV4`:
//
// 2. Client software **MUST** return `-38005: Unsupported fork` error if the
// `payloadAttributes` is set and the `payloadAttributes.timestamp` does not fall within
// the time frame of the Prague fork.
//
// For `engine_newPayloadV4`:
//
// 2. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of
// the payload does not fall within the time frame of the Prague fork.
return Err(EngineObjectValidationError::UnsupportedFork)
}
Ok(())
}
/// Validates the presence of the `withdrawals` field according to the payload timestamp.
/// After Shanghai, withdrawals field must be [Some].
/// Before Shanghai, withdrawals field must be [None];
pub fn validate_withdrawals_presence<T: EthereumHardforks>(
chain_spec: &T,
version: EngineApiMessageVersion,
message_validation_kind: MessageValidationKind,
timestamp: u64,
has_withdrawals: bool,
) -> Result<(), EngineObjectValidationError> {
let is_shanghai_active = chain_spec.is_shanghai_active_at_timestamp(timestamp);
match version {
EngineApiMessageVersion::V1 => {
if has_withdrawals {
return Err(message_validation_kind
.to_error(VersionSpecificValidationError::WithdrawalsNotSupportedInV1))
}
}
EngineApiMessageVersion::V2 | EngineApiMessageVersion::V3 | EngineApiMessageVersion::V4 => {
if is_shanghai_active && !has_withdrawals {
return Err(message_validation_kind
.to_error(VersionSpecificValidationError::NoWithdrawalsPostShanghai))
}
if !is_shanghai_active && has_withdrawals {
return Err(message_validation_kind
.to_error(VersionSpecificValidationError::HasWithdrawalsPreShanghai))
}
}
};
Ok(())
}
/// Validate the presence of the `parentBeaconBlockRoot` field according to the given timestamp.
/// This method is meant to be used with either a `payloadAttributes` field or a full payload, with
/// the `engine_forkchoiceUpdated` and `engine_newPayload` methods respectively.
///
/// After Cancun, the `parentBeaconBlockRoot` field must be [Some].
/// Before Cancun, the `parentBeaconBlockRoot` field must be [None].
///
/// If the engine API message version is V1 or V2, and the timestamp is post-Cancun, then this will
/// return [`EngineObjectValidationError::UnsupportedFork`].
///
/// If the timestamp is before the Cancun fork and the engine API message version is V3, then this
/// will return [`EngineObjectValidationError::UnsupportedFork`].
///
/// If the engine API message version is V3, but the `parentBeaconBlockRoot` is [None], then
/// this will return [`VersionSpecificValidationError::NoParentBeaconBlockRootPostCancun`].
///
/// This implements the following Engine API spec rules:
///
/// 1. Client software **MUST** check that provided set of parameters and their fields strictly
/// matches the expected one and return `-32602: Invalid params` error if this check fails. Any
/// field having `null` value **MUST** be considered as not provided.
///
/// For `engine_forkchoiceUpdatedV3`:
///
/// 1. Client software **MUST** check that provided set of parameters and their fields strictly
/// matches the expected one and return `-32602: Invalid params` error if this check fails. Any
/// field having `null` value **MUST** be considered as not provided.
///
/// 2. Extend point (7) of the `engine_forkchoiceUpdatedV1` specification by defining the following
/// sequence of checks that **MUST** be run over `payloadAttributes`:
/// 1. `payloadAttributes` matches the `PayloadAttributesV3` structure, return `-38003: Invalid
/// payload attributes` on failure.
/// 2. `payloadAttributes.timestamp` falls within the time frame of the Cancun fork, return
/// `-38005: Unsupported fork` on failure.
/// 3. `payloadAttributes.timestamp` is greater than `timestamp` of a block referenced by
/// `forkchoiceState.headBlockHash`, return `-38003: Invalid payload attributes` on failure.
/// 4. If any of the above checks fails, the `forkchoiceState` update **MUST NOT** be rolled
/// back.
///
/// For `engine_newPayloadV3`:
///
/// 2. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of the
/// payload does not fall within the time frame of the Cancun fork.
///
/// For `engine_newPayloadV4`:
///
/// 2. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of the
/// payload does not fall within the time frame of the Prague fork.
///
/// Returning the right error code (ie, if the client should return `-38003: Invalid payload
/// attributes` is handled by the `message_validation_kind` parameter. If the parameter is
/// `MessageValidationKind::Payload`, then the error code will be `-32602: Invalid params`. If the
/// parameter is `MessageValidationKind::PayloadAttributes`, then the error code will be `-38003:
/// Invalid payload attributes`.
pub fn validate_parent_beacon_block_root_presence<T: EthereumHardforks>(
chain_spec: &T,
version: EngineApiMessageVersion,
validation_kind: MessageValidationKind,
timestamp: u64,
has_parent_beacon_block_root: bool,
) -> Result<(), EngineObjectValidationError> {
// 1. Client software **MUST** check that provided set of parameters and their fields strictly
// matches the expected one and return `-32602: Invalid params` error if this check fails.
// Any field having `null` value **MUST** be considered as not provided.
//
// For `engine_forkchoiceUpdatedV3`:
//
// 2. Extend point (7) of the `engine_forkchoiceUpdatedV1` specification by defining the
// following sequence of checks that **MUST** be run over `payloadAttributes`:
// 1. `payloadAttributes` matches the `PayloadAttributesV3` structure, return `-38003:
// Invalid payload attributes` on failure.
// 2. `payloadAttributes.timestamp` falls within the time frame of the Cancun fork, return
// `-38005: Unsupported fork` on failure.
// 3. `payloadAttributes.timestamp` is greater than `timestamp` of a block referenced by
// `forkchoiceState.headBlockHash`, return `-38003: Invalid payload attributes` on
// failure.
// 4. If any of the above checks fails, the `forkchoiceState` update **MUST NOT** be rolled
// back.
match version {
EngineApiMessageVersion::V1 | EngineApiMessageVersion::V2 => {
if has_parent_beacon_block_root {
return Err(validation_kind.to_error(
VersionSpecificValidationError::ParentBeaconBlockRootNotSupportedBeforeV3,
))
}
}
EngineApiMessageVersion::V3 | EngineApiMessageVersion::V4 => {
if !has_parent_beacon_block_root {
return Err(validation_kind
.to_error(VersionSpecificValidationError::NoParentBeaconBlockRootPostCancun))
}
}
};
// For `engine_forkchoiceUpdatedV3`:
//
// 2. Client software **MUST** return `-38005: Unsupported fork` error if the
// `payloadAttributes` is set and the `payloadAttributes.timestamp` does not fall within the
// time frame of the Cancun fork.
//
// For `engine_newPayloadV3`:
//
// 2. Client software **MUST** return `-38005: Unsupported fork` error if the `timestamp` of the
// payload does not fall within the time frame of the Cancun fork.
validate_payload_timestamp(chain_spec, version, timestamp)?;
Ok(())
}
/// A type that represents whether or not we are validating a payload or payload attributes.
///
/// This is used to ensure that the correct error code is returned when validating the payload or
/// payload attributes.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum MessageValidationKind {
/// We are validating fields of a payload attributes.
PayloadAttributes,
/// We are validating fields of a payload.
Payload,
}
impl MessageValidationKind {
/// Returns an `EngineObjectValidationError` based on the given
/// `VersionSpecificValidationError` and the current validation kind.
pub const fn to_error(
self,
error: VersionSpecificValidationError,
) -> EngineObjectValidationError {
match self {
Self::Payload => EngineObjectValidationError::Payload(error),
Self::PayloadAttributes => EngineObjectValidationError::PayloadAttributes(error),
}
}
}
/// Validates the presence or exclusion of fork-specific fields based on the ethereum execution
/// payload, or payload attributes, and the message version.
///
/// The object being validated is provided by the [`PayloadOrAttributes`] argument, which can be
/// either an execution payload, or payload attributes.
///
/// The version is provided by the [`EngineApiMessageVersion`] argument.
pub fn validate_version_specific_fields<Type, T>(
chain_spec: &T,
version: EngineApiMessageVersion,
payload_or_attrs: PayloadOrAttributes<'_, Type>,
) -> Result<(), EngineObjectValidationError>
where
Type: PayloadAttributes,
T: EthereumHardforks,
{
validate_withdrawals_presence(
chain_spec,
version,
payload_or_attrs.message_validation_kind(),
payload_or_attrs.timestamp(),
payload_or_attrs.withdrawals().is_some(),
)?;
validate_parent_beacon_block_root_presence(
chain_spec,
version,
payload_or_attrs.message_validation_kind(),
payload_or_attrs.timestamp(),
payload_or_attrs.parent_beacon_block_root().is_some(),
)
}
/// The version of Engine API message.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Default)]
pub enum EngineApiMessageVersion {
/// Version 1
V1 = 1,
/// Version 2
///
/// Added in the Shanghai hardfork.
V2 = 2,
/// Version 3
///
/// Added in the Cancun hardfork.
#[default]
V3 = 3,
/// Version 4
///
/// Added in the Prague hardfork.
V4 = 4,
}
/// Determines how we should choose the payload to return.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum PayloadKind {
/// Returns the next best available payload (the earliest available payload).
/// This does not wait for a real for pending job to finish if there's no best payload yet and
/// is allowed to race various payload jobs (empty, pending best) against each other and
/// returns whichever job finishes faster.
///
/// This should be used when it's more important to return a valid payload as fast as possible.
/// For example, the engine API timeout for `engine_getPayload` is 1s and clients should rather
/// return an empty payload than indefinitely waiting for the pending payload job to finish and
/// risk missing the deadline.
#[default]
Earliest,
/// Only returns once we have at least one built payload.
///
/// Compared to [`PayloadKind::Earliest`] this does not race an empty payload job against the
/// already in progress one, and returns the best available built payload or awaits the job in
/// progress.
WaitForPending,
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn version_ord() {
assert!(EngineApiMessageVersion::V4 > EngineApiMessageVersion::V3);
}
}