feat: platform-specific limit extension

Author: julio4

examples/custom-bundle-type.rs

@@ -32,6 +32,7 @@ impl Platform for CustomPlatform {
 	type Bundle = CustomBundleType;
 	type DefaultLimits = types::DefaultLimits<Optimism>;
 	type EvmConfig = types::EvmConfig<Optimism>;
+	type ExtraLimits = types::ExtraLimits<Optimism>;
 	type NodeTypes = types::NodeTypes<Optimism>;
 	type PooledTransaction = types::PooledTransaction<Optimism>;
 

src/pipelines/exec/scope.rs

@@ -82,7 +82,7 @@ impl<P: Platform> RootScope<P> {
 	}
 
 	/// Given a path to a step in the pipeline, returns its current limits.
-	pub(crate) fn limits_of(&self, step_path: &StepPath) -> Option<Limits> {
+	pub(crate) fn limits_of(&self, step_path: &StepPath) -> Option<Limits<P>> {
 		self
 			.root
 			.read()
@@ -169,7 +169,7 @@ fn scope_of(step: &StepPath) -> StepPath {
 /// that contain it. When a scope is active, then all its parent scopes are
 /// active as well.
 pub(crate) struct Scope<P: Platform> {
-	limits: Limits,
+	limits: Limits<P>,
 	metrics: Metrics,
 	limits_factory: Option<Arc<dyn ScopedLimits<P>>>,
 	entered_at: Option<Instant>,
@@ -197,7 +197,7 @@ impl<P: Platform> Scope<P> {
 	}
 
 	/// Returns the payload limits for steps running within the current scope.
-	pub(crate) const fn limits(&self) -> &Limits {
+	pub(crate) const fn limits(&self) -> &Limits<P> {
 		&self.limits
 	}
 }
@@ -240,7 +240,7 @@ impl<P: Platform> Scope<P> {
 		}
 	}
 
-	fn enter(&mut self, checkpoint: &Checkpoint<P>, enclosing: &Limits) {
+	fn enter(&mut self, checkpoint: &Checkpoint<P>, enclosing: &Limits<P>) {
 		assert!(!self.is_active(), "Scope is already active");
 
 		// refresh limits of this scope
@@ -308,7 +308,7 @@ impl<P: Platform> Scope<P> {
 		checkpoint: &Checkpoint<P>,
 		path: &StepPath,
 		root_name: &str,
-		enclosing: &Limits,
+		enclosing: &Limits<P>,
 	) -> Self {
 		let limits_factory = local.limits().cloned();
 		let scope_limits = limits_factory

src/pipelines/limits.rs

@@ -18,7 +18,8 @@ pub trait ScopedLimits<P: Platform>: Send + Sync + 'static {
 	/// As an input this method receives the current payload checkpoint and the
 	/// limits imposed by its parent scope (or limits created by
 	/// `PlatformLimits`).
-	fn create(&self, payload: &Checkpoint<P>, enclosing: &Limits) -> Limits;
+	fn create(&self, payload: &Checkpoint<P>, enclosing: &Limits<P>)
+	-> Limits<P>;
 }
 
 /// Convenience trait that allows API users to either use a `ScopedLimits` type
@@ -34,11 +35,11 @@ impl<T: ScopedLimits<P>, P: Platform> IntoScopedLimits<P, Variant<0>> for T {
 	}
 }
 
-impl<P: Platform> IntoScopedLimits<P, Variant<1>> for Limits {
+impl<P: Platform> IntoScopedLimits<P, Variant<1>> for Limits<P> {
 	fn into_scoped_limits(self) -> impl ScopedLimits<P> {
-		struct FixedLimits(Limits);
-		impl<P: Platform> ScopedLimits<P> for FixedLimits {
-			fn create(&self, _: &Checkpoint<P>, _: &Limits) -> Limits {
+		struct FixedLimits<P: Platform>(Limits<P>);
+		impl<P: Platform> ScopedLimits<P> for FixedLimits<P> {
+			fn create(&self, _: &Checkpoint<P>, _: &Limits<P>) -> Limits<P> {
 				self.0
 			}
 		}
@@ -104,7 +105,7 @@ impl<T> From<Zero> for ScaleOp<T> {
 }
 
 impl<P: Platform> ScopedLimits<P> for Scaled {
-	fn create(&self, _: &Checkpoint<P>, enclosing: &Limits) -> Limits {
+	fn create(&self, _: &Checkpoint<P>, enclosing: &Limits<P>) -> Limits<P> {
 		self.from(enclosing)
 	}
 }
@@ -121,7 +122,7 @@ impl Scaled {
 		}
 	}
 
-	pub fn from(&self, limits: &Limits) -> Limits {
+	pub fn from<P: Platform>(&self, limits: &Limits<P>) -> Limits<P> {
 		let mut limits = *limits;
 
 		if let Some(ref op) = self.gas {

src/pipelines/mod.rs

@@ -409,12 +409,20 @@ pub mod traits {
 	}
 
 	pub trait PlatformExecBounds<P: Platform>:
-		Platform<NodeTypes = types::NodeTypes<P>, EvmConfig = types::EvmConfig<P>>
+		Platform<
+			NodeTypes = types::NodeTypes<P>,
+			EvmConfig = types::EvmConfig<P>,
+			ExtraLimits = types::ExtraLimits<P>,
+		>
 	{
 	}
 
 	impl<T, P: Platform> PlatformExecBounds<T> for P where
-		T: Platform<NodeTypes = types::NodeTypes<P>, EvmConfig = types::EvmConfig<P>>
+		T: Platform<
+				NodeTypes = types::NodeTypes<P>,
+				EvmConfig = types::EvmConfig<P>,
+				ExtraLimits = types::ExtraLimits<P>,
+			>
 	{
 	}
 }

src/pipelines/step/context.rs

@@ -16,7 +16,7 @@ use {
 #[derive(Debug, Clone)]
 pub struct StepContext<P: Platform> {
 	block: BlockContext<P>,
-	limits: Limits,
+	limits: Limits<P>,
 	events_bus: Arc<EventsBus<P>>,
 	started_at: Option<Instant>,
 }
@@ -25,7 +25,7 @@ impl<P: Platform> StepContext<P> {
 	pub(crate) fn new(
 		block: &BlockContext<P>,
 		step: &StepNavigator<P>,
-		limits: Limits,
+		limits: Limits<P>,
 		in_scope_since: Option<Instant>,
 	) -> Self {
 		let block = block.clone();
@@ -60,7 +60,7 @@ impl<P: Platform> StepContext<P> {
 	}
 
 	/// Payload limits for the scope of the step.
-	pub const fn limits(&self) -> &Limits {
+	pub const fn limits(&self) -> &Limits<P> {
 		&self.limits
 	}
 

src/pipelines/tests/syntax.rs

@@ -104,7 +104,7 @@ fn flashblocks_example_closure() {
 	#[derive(Debug)]
 	struct FlashblockLimits(FlashblocksConfig);
 	impl<P: Platform> ScopedLimits<P> for FlashblockLimits {
-		fn create(&self, _: &Checkpoint<P>, _: &Limits) -> Limits {
+		fn create(&self, _: &Checkpoint<P>, _: &Limits<P>) -> Limits<P> {
 			unimplemented!()
 		}
 	}

src/platform/ethereum/limits.rs

@@ -23,7 +23,7 @@ impl EthereumDefaultLimits {
 }
 
 impl PlatformLimits<Ethereum> for EthereumDefaultLimits {
-	fn create(&self, block: &BlockContext<Ethereum>) -> Limits {
+	fn create(&self, block: &BlockContext<Ethereum>) -> Limits<Ethereum> {
 		let timestamp = block.attributes().timestamp();
 		let parent_gas_limit = block.parent().gas_limit();
 		let gas_limit = self.0.gas_limit(parent_gas_limit);

src/platform/ethereum/mod.rs

@@ -69,6 +69,7 @@ impl Platform for Ethereum {
 	type Bundle = FlashbotsBundle<Self>;
 	type DefaultLimits = EthereumDefaultLimits;
 	type EvmConfig = EthEvmConfig;
+	type ExtraLimits = ();
 	type NodeTypes = EthereumNode;
 	type PooledTransaction = EthPooledTransaction;
 

src/platform/limits.rs

@@ -2,7 +2,7 @@ use {
 	crate::{alloy::eips::eip7840::BlobParams, prelude::*},
 	core::time::Duration,
 	serde::{Deserialize, Serialize},
-	std::time::Instant,
+	std::{fmt::Debug, time::Instant},
 };
 
 /// This type specifies the limits that payloads should stay within.
@@ -12,8 +12,8 @@ use {
 /// - Limits are specified on a pipeline scope level. If a pipeline scope
 ///   doesn't explicitly specify its limits it will inherit its enclosing scope
 ///   limits.
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
-pub struct Limits {
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct Limits<P: Platform> {
 	/// The maximum cumulative gas that can be used in the block.
 	/// This includes all transactions, epilogues, prologues, and other
 	/// gas-consuming operations.
@@ -24,12 +24,29 @@ pub struct Limits {
 
 	/// The maximum number of transactions that can be included in the block.
 	///
-	/// This is not a standard known ethereum limit, however it can be imposed by
-	/// custom limits factories.
+	/// This is not a standard known ethereum limit; however, it can be imposed
+	/// by custom limits factories.
 	pub max_transactions: Option<usize>,
 
 	/// The time a pipeline is allowed to spend on execution.
 	pub deadline: Option<Duration>,
+
+	/// Per platform extension.
+	pub ext: P::ExtraLimits,
+}
+
+impl<P: Platform> Copy for Limits<P> {}
+
+/// This trait must be implemented by extension limits
+pub trait LimitExtension:
+	Copy + Debug + Default + Send + Sync + 'static
+{
+	#[must_use]
+	fn clamp(&self, other: &Self) -> Self;
+}
+
+impl LimitExtension for () {
+	fn clamp(&self, (): &Self) -> Self {}
 }
 
 /// Types implementing this trait are responsible for calculating top-level
@@ -39,16 +56,17 @@ pub struct Limits {
 /// Implementations of this type are always called exactly once at the beginning
 /// of a new payload job.
 pub trait PlatformLimits<P: Platform>: Default + Send + Sync + 'static {
-	fn create(&self, block: &BlockContext<P>) -> Limits;
+	fn create(&self, block: &BlockContext<P>) -> Limits<P>;
 }
 
-impl Limits {
+impl<P: Platform> Limits<P> {
 	pub fn gas_limit(gas_limit: u64) -> Self {
 		Self {
 			gas_limit,
 			blob_params: None,
 			deadline: None,
 			max_transactions: None,
+			ext: P::ExtraLimits::default(),
 		}
 	}
 
@@ -109,6 +127,7 @@ impl Limits {
 			},
 			max_transactions: self.max_transactions.min(other.max_transactions),
 			deadline: self.deadline.min(other.deadline),
+			ext: self.ext.clamp(&other.ext),
 		}
 	}
 }

src/platform/mod.rs

@@ -31,7 +31,7 @@ mod optimism;
 #[cfg(feature = "optimism")]
 pub use optimism::*;
 
-/// This type abstracts the platform specific types of the underlying node that
+/// This type abstracts the platform-specific types of the underlying node that
 /// is building block payloads.
 ///
 /// The payload builder API is agnostic to the underlying payload types, header
@@ -85,6 +85,11 @@ pub trait Platform:
 	/// type will be used automatically.
 	type DefaultLimits: PlatformLimits<Self>;
 
+	/// Type that can provide extra limits for the payload building process.
+	/// This type is used to provide platform-specific limits that are not
+	/// covered by the default `Limits` type.
+	type ExtraLimits: LimitExtension;
+
 	/// Instantiate the EVM configuration for the platform with a given chain
 	/// specification.
 	fn evm_config<P>(chainspec: Arc<types::ChainSpec<P>>) -> Self::EvmConfig