refactor(gas_limiter): canonical + overlay design with epoch tag (#488)

* refactor(gas_limiter): canonical + overlay design with epoch tag

* fixes

Author: julio4

crates/op-rbuilder/src/builder/context.rs

@@ -35,7 +35,7 @@ use crate::{
     },
     evm::OpBlockEvmFactory,
     hardforks::ActiveHardforks,
-    limiter::AddressLimiter,
+    limiter::{AddressLimiter, AddressLimiterGuard},
     metrics::OpRBuilderMetrics,
     primitives::reth::{ExecutionInfo, TxnExecutionResult},
     traits::PayloadTxsBounds,
@@ -64,8 +64,9 @@ pub struct OpPayloadBuilderCtx {
     pub max_gas_per_txn: Option<u64>,
     /// Maximum cumulative uncompressed (EIP-2718 encoded) block size in bytes.
     pub max_uncompressed_block_size: Option<u64>,
-    /// Per-address rate limiting based on gas and/or compute time. This is an
-    /// optional feature.
+    /// Canonical per-address rate limiter (gas and/or compute time). Each
+    /// payload job begins a per-build [`AddressLimiterGuard`] off this; the
+    /// only direct mutation here is the per-block `refill_buckets`.
     pub address_limiter: AddressLimiter,
     /// Backrun bundle configuration.
     pub backrun_bundle_args: BackrunBundleArgs,
@@ -82,6 +83,7 @@ pub struct OpPayloadBuilderCtx {
 /// Container type that holds all necessities to build a new payload.
 /// This struct is constructed once per payload job.
 #[derive(derive_more::Constructor, derive_more::Deref)]
+#[allow(clippy::too_many_arguments)]
 pub struct OpPayloadJobCtx {
     /// Builder-lifetime configuration shared with all other in-flight jobs.
     #[deref]
@@ -98,6 +100,12 @@ pub struct OpPayloadJobCtx {
     cancel: FlashblockJobCancellation,
     /// Per-block view into the global backrun bundle pool.
     backrun_pool: Option<BackrunBundlePayloadPool>,
+    /// Per-build guard onto the canonical [`AddressLimiter`] held by
+    /// `builder_ctx`. Charges accumulate privately here and auto-commit back
+    /// into the canonical when this ctx is dropped. Shadows the
+    /// `address_limiter` field reached via `Deref` to `OpPayloadBuilderCtx`,
+    /// so `self.address_limiter` inside this ctx always hits the guard.
+    address_limiter: AddressLimiterGuard,
 }
 
 impl OpPayloadJobCtx {

crates/op-rbuilder/src/builder/payload.rs

@@ -403,6 +403,8 @@ where
             .backrun_bundle_pool()
             .map(|pool| pool.block_pool(config.parent_header.number + 1));
 
+        let address_limiter = builder_ctx.address_limiter.begin();
+
         Ok(OpPayloadJobCtx::new(
             Arc::clone(builder_ctx),
             evm_factory,
@@ -411,6 +413,7 @@ where
             hardforks,
             cancel,
             backrun_pool,
+            address_limiter,
         ))
     }
 
@@ -442,6 +445,10 @@ where
             config.attributes.payload_attributes.id.to_string(),
         );
 
+        self.builder_ctx
+            .address_limiter
+            .refill_buckets(config.parent_header.number + 1);
+
         let ctx = self
             .get_op_payload_job_ctx(config.clone(), payload_cancel.flashblock_child())
             .map_err(|e| PayloadBuilderError::Other(e.into()))?;
@@ -457,8 +464,6 @@ where
             ctx.enable_incremental_state_root,
         );
 
-        ctx.address_limiter.refresh(ctx.block_number());
-
         // Phase 1: Build the fallback block.
         let fallback_span = if span.is_none() {
             tracing::Span::none()