feat(op-reth): gate payload builder on interop failsafe (#21448)

* feat(op-reth): gate payload builder on interop failsafe

The payload builder never read the supervisor interop failsafe, so it kept
sealing interop txs into unsafe blocks during a failsafe window until async
pool eviction caught up, and it never excluded interop txs that bypassed the
filter (e.g. private or locally-submitted txs).

Thread a shared InteropFailsafe handle (Arc<AtomicBool>, mirroring
SdmPostExecOptIn) from the txpool interop filter client (writer) through node
setup into OpBuilderConfig (reader). When the failsafe is active, the build
loop now excludes every interop tx, detected intrinsically via its
CrossL2Inbox access list rather than the pool's interop-deadline marker, so
unfiltered interop txs are caught too.

* docs(op-reth): tighten interop failsafe comments

* test(op-reth): assert interop tx re-includes after failsafe clears

Thread one shared InteropFailsafe handle through three builds (off, on,
off) so the test proves the gate is re-evaluated per build and the
mark_invalid an excluded interop tx triggers does not persist once the
failsafe clears.

Author: ajsutton

rust/op-reth/crates/node/src/node.rs

@@ -52,7 +52,9 @@ use reth_optimism_rpc::{
     witness::{DebugExecutionWitnessApiServer, OpDebugPostExecApiServer, OpDebugWitnessApi},
 };
 use reth_optimism_storage::OpStorage;
-use reth_optimism_txpool::{OpPool, OpPooledTx, interop_filter::InteropFilterClient};
+use reth_optimism_txpool::{
+    OpPool, OpPooledTx, interop::InteropFailsafe, interop_filter::InteropFilterClient,
+};
 use reth_primitives_traits::header::HeaderMut;
 use reth_provider::{CanonStateSubscriptions, providers::ProviderFactoryBuilder};
 use reth_rpc_api::{
@@ -207,6 +209,9 @@ pub struct OpNode {
     /// Local operator opt-in for SDM `PostExec` production. Shared (via Arc clones) between the
     /// payload builder and the `admin_setSdmPostExecOptIn` RPC handler.
     pub sdm_post_exec_opt_in: SdmPostExecOptIn,
+    /// Interop failsafe gate, shared between the txpool's interop filter client (writer) and the
+    /// payload builder (reader, to exclude interop txs while it is active).
+    pub interop_failsafe: InteropFailsafe,
 }
 
 /// A [`ComponentsBuilder`] with its generic arguments set to a stack of Optimism specific builders.
@@ -227,6 +232,7 @@ impl OpNode {
             da_config: OpDAConfig::default(),
             gas_limit_config: OpGasLimitConfig::default(),
             sdm_post_exec_opt_in: SdmPostExecOptIn::default(),
+            interop_failsafe: InteropFailsafe::default(),
         }
     }
 
@@ -259,13 +265,15 @@ impl OpNode {
                         self.args.interop_http.clone(),
                         self.args.interop_min_responses,
                         self.args.interop_safety_level,
-                    ),
+                    )
+                    .with_interop_failsafe(self.interop_failsafe.clone()),
             )
             .payload(BasicPayloadServiceBuilder::new(
                 OpPayloadBuilder::new(compute_pending_block)
                     .with_da_config(self.da_config.clone())
                     .with_gas_limit_config(self.gas_limit_config.clone())
                     .with_sdm_post_exec_opt_in(self.sdm_post_exec_opt_in.clone())
+                    .with_interop_failsafe(self.interop_failsafe.clone())
                     .with_max_uncompressed_block_size(self.args.max_uncompressed_block_size),
             ))
             .network(OpNetworkBuilder::new(disable_txpool_gossip, !discovery_v4))
@@ -1083,6 +1091,8 @@ pub struct OpPoolBuilder<T = crate::txpool::OpPooledTransaction> {
     pub interop_min_responses: Option<usize>,
     /// Safety level for interop filter validation.
     pub interop_safety_level: SafetyLevel,
+    /// Shared interop failsafe gate, passed to the interop filter client this builder constructs.
+    pub interop_failsafe: InteropFailsafe,
     /// Marker for the pooled transaction type.
     _pd: core::marker::PhantomData<T>,
 }
@@ -1095,6 +1105,7 @@ impl<T> Default for OpPoolBuilder<T> {
             interop_endpoints: Vec::new(),
             interop_min_responses: None,
             interop_safety_level: SafetyLevel::CrossUnsafe,
+            interop_failsafe: InteropFailsafe::default(),
             _pd: Default::default(),
         }
     }
@@ -1108,6 +1119,7 @@ impl<T> Clone for OpPoolBuilder<T> {
             interop_endpoints: self.interop_endpoints.clone(),
             interop_min_responses: self.interop_min_responses,
             interop_safety_level: self.interop_safety_level,
+            interop_failsafe: self.interop_failsafe.clone(),
             _pd: core::marker::PhantomData,
         }
     }
@@ -1143,6 +1155,12 @@ impl<T> OpPoolBuilder<T> {
         self.interop_safety_level = interop_safety_level;
         self
     }
+
+    /// Shares the interop failsafe gate, written by the interop filter client this builder builds.
+    pub fn with_interop_failsafe(mut self, interop_failsafe: InteropFailsafe) -> Self {
+        self.interop_failsafe = interop_failsafe;
+        self
+    }
 }
 
 impl<Node, T, Evm> PoolBuilder<Node, Evm> for OpPoolBuilder<T>
@@ -1180,7 +1198,8 @@ where
                 self.interop_endpoints.clone(),
                 ctx.chain_spec().chain_id(),
             )
-            .minimum_safety(self.interop_safety_level);
+            .minimum_safety(self.interop_safety_level)
+            .failsafe(self.interop_failsafe.clone());
             if let Some(min) = self.interop_min_responses {
                 builder = builder.min_responses(min);
             }
@@ -1302,6 +1321,8 @@ pub struct OpPayloadBuilder<Txs = ()> {
     pub gas_limit_config: OpGasLimitConfig,
     /// Operator opt-in flag for SDM `PostExec` production. Shared with the admin RPC.
     pub sdm_post_exec_opt_in: SdmPostExecOptIn,
+    /// Interop failsafe gate, read by the builder to exclude interop txs while it is active.
+    pub interop_failsafe: InteropFailsafe,
     /// Maximum cumulative uncompressed (EIP-2718 encoded) block size in bytes.
     ///
     /// `None` disables the limit. See
@@ -1319,6 +1340,7 @@ impl OpPayloadBuilder {
             da_config: OpDAConfig::default(),
             gas_limit_config: OpGasLimitConfig::default(),
             sdm_post_exec_opt_in: SdmPostExecOptIn::default(),
+            interop_failsafe: InteropFailsafe::default(),
             max_uncompressed_block_size: None,
         }
     }
@@ -1350,6 +1372,13 @@ impl OpPayloadBuilder {
         self.sdm_post_exec_opt_in = sdm_post_exec_opt_in;
         self
     }
+
+    /// Provide the shared interop failsafe gate read by the builder.
+    #[must_use]
+    pub fn with_interop_failsafe(mut self, interop_failsafe: InteropFailsafe) -> Self {
+        self.interop_failsafe = interop_failsafe;
+        self
+    }
 }
 
 impl<Txs> OpPayloadBuilder<Txs> {
@@ -1361,6 +1390,7 @@ impl<Txs> OpPayloadBuilder<Txs> {
             da_config,
             gas_limit_config,
             sdm_post_exec_opt_in,
+            interop_failsafe,
             max_uncompressed_block_size,
             ..
         } = self;
@@ -1370,6 +1400,7 @@ impl<Txs> OpPayloadBuilder<Txs> {
             da_config,
             gas_limit_config,
             sdm_post_exec_opt_in,
+            interop_failsafe,
             max_uncompressed_block_size,
         }
     }
@@ -1421,6 +1452,7 @@ where
                 da_config: self.da_config.clone(),
                 gas_limit_config: self.gas_limit_config.clone(),
                 sdm_post_exec_opt_in: self.sdm_post_exec_opt_in.clone(),
+                interop_failsafe: self.interop_failsafe.clone(),
                 max_uncompressed_block_size: self.max_uncompressed_block_size,
             },
         )

rust/op-reth/crates/payload/src/builder.rs

@@ -35,7 +35,7 @@ use reth_optimism_primitives::{L2_TO_L1_MESSAGE_PASSER_ADDRESS, OpTransaction};
 use reth_optimism_txpool::{
     OpPooledTx,
     estimated_da_size::DataAvailabilitySized,
-    interop::{MaybeInteropTransaction, is_valid_interop},
+    interop::{MaybeInteropTransaction, is_interop_tx, is_valid_interop},
 };
 use reth_payload_builder_primitives::PayloadBuilderError;
 use reth_payload_primitives::{BuildNextEnv, BuiltPayloadExecutedBlock};
@@ -978,6 +978,10 @@ where
         let tx_da_limit = self.builder_config.da_config.max_da_tx_size();
         let max_uncompressed_block_size = self.builder_config.max_uncompressed_block_size;
         let base_fee = builder.evm_mut().block().basefee();
+        // Snapshot the interop failsafe once for this build. Gating here, rather than relying on
+        // async pool eviction, excludes interop txs that bypassed the filter (e.g. private or
+        // local txs) and avoids racing eviction to drain the pool.
+        let interop_failsafe_active = self.builder_config.interop_failsafe.enabled();
 
         while let Some(tx) = best_txs.next(()) {
             let interop = tx.interop_deadline();
@@ -1023,6 +1027,12 @@ where
                 continue;
             }
 
+            // While the failsafe is active, exclude every interop tx regardless of its deadline.
+            if interop_failsafe_active && is_interop_tx(&*tx) {
+                best_txs.mark_invalid(tx.signer(), tx.nonce());
+                continue;
+            }
+
             // We skip invalid cross chain txs, they would be removed on the next block update in
             // the maintenance job
             if let Some(interop) = interop &&

rust/op-reth/crates/payload/src/builder/tests.rs

@@ -8,7 +8,7 @@ use alloy_consensus::{
 };
 use alloy_eips::{
     eip2718::{Encodable2718, WithEncoded},
-    eip2930::AccessList,
+    eip2930::{AccessList, AccessListItem},
     eip7702::SignedAuthorization,
 };
 use alloy_evm::RecoveredTx;
@@ -22,8 +22,11 @@ use reth_optimism_chainspec::{OpChainSpec, OpChainSpecBuilder};
 use reth_optimism_evm::{OpEvmConfig, PostExecMode};
 use reth_optimism_primitives::{OpPrimitives, OpTransactionSigned};
 use reth_optimism_txpool::{
-    OpPooledTransaction, OpPooledTx, conditional::MaybeConditionalTransaction,
-    estimated_da_size::DataAvailabilitySized, interop::MaybeInteropTransaction,
+    OpPooledTransaction, OpPooledTx,
+    conditional::MaybeConditionalTransaction,
+    estimated_da_size::DataAvailabilitySized,
+    interop::{InteropFailsafe, MaybeInteropTransaction},
+    interop_filter::CROSS_L2_INBOX_ADDRESS,
 };
 use reth_payload_builder_primitives::PayloadBuilderError;
 use reth_payload_util::PayloadTransactionsFixed;
@@ -165,6 +168,31 @@ fn op_pooled_tx(nonce: u64, signer: Address, recipient: Address) -> OpPooledTran
     OpPooledTransaction::new(Recovered::new_unchecked(tx, signer), encoded_len)
 }
 
+/// Builds an interop pool tx: a `CROSS_L2_INBOX_ADDRESS` access-list entry makes `is_interop_tx`
+/// match it; the gas limit covers the access-list intrinsic cost so it executes when failsafe is
+/// off.
+fn op_interop_pooled_tx(nonce: u64, signer: Address, recipient: Address) -> OpPooledTransaction {
+    let tx: OpTransactionSigned = TxEip1559 {
+        chain_id: 8453,
+        nonce,
+        gas_limit: 100_000,
+        max_fee_per_gas: 1,
+        max_priority_fee_per_gas: 1,
+        to: TxKind::Call(recipient),
+        value: U256::ZERO,
+        access_list: AccessList(vec![AccessListItem {
+            address: CROSS_L2_INBOX_ADDRESS,
+            storage_keys: vec![B256::ZERO],
+        }]),
+        ..Default::default()
+    }
+    .into_signed(Signature::test_signature())
+    .into();
+    let encoded_len = tx.encode_2718_len();
+
+    OpPooledTransaction::new(Recovered::new_unchecked(tx, signer), encoded_len)
+}
+
 fn tx_hashes<'a>(txs: impl IntoIterator<Item = &'a Recovered<OpTransactionSigned>>) -> Vec<TxHash> {
     txs.into_iter().map(|tx| *TxHashRef::tx_hash(tx)).collect()
 }
@@ -181,7 +209,23 @@ where
     let gas_limit = 1_000_000;
     let chain_spec = Arc::new(OpChainSpecBuilder::base_mainnet().regolith_activated().build());
     let ctx = payload_builder_ctx(chain_spec, gas_limit);
+    run_execute_best_transactions_with_ctx(ctx, signer, txs, gas_limit_cap, committed_txs)
+}
 
+fn run_execute_best_transactions_with_ctx<T>(
+    ctx: OpPayloadBuilderCtx<
+        OpEvmConfig<OpChainSpec, OpPrimitives>,
+        OpChainSpec,
+        OpPayloadBuilderAttributes<OpTransactionSigned>,
+    >,
+    signer: Address,
+    txs: Vec<T>,
+    gas_limit_cap: Option<u64>,
+    committed_txs: Option<&mut Vec<Recovered<OpTransactionSigned>>>,
+) -> (ExecutionInfo, Vec<TxHash>)
+where
+    T: PoolTransaction<Consensus = OpTransactionSigned> + OpPooledTx,
+{
     let mut state_provider = StateProviderTest::default();
     state_provider.insert_account(
         signer,
@@ -600,3 +644,49 @@ fn miner_fee_uses_pool_wrapper_tip() {
     assert_eq!(info.total_fees, expected_fees);
     assert_ne!(info.total_fees, natural_fees);
 }
+
+/// With the failsafe active the builder excludes interop txs but keeps normal txs; with it off the
+/// same interop tx is included — proving the gate is flag-driven, not a blanket exclusion, and does
+/// not depend on the pool's interop-deadline marker. Clearing the flag and rebuilding includes the
+/// interop tx again, proving the exclusion is a per-build decision and the `mark_invalid` it
+/// triggers does not stick across builds.
+#[test]
+fn execute_best_transactions_excludes_interop_txs_when_failsafe_active() {
+    let signer = Address::repeat_byte(0x11);
+    let normal = op_pooled_tx(0, signer, Address::repeat_byte(0x22));
+    let interop = op_interop_pooled_tx(1, signer, Address::repeat_byte(0x33));
+    let normal_hash = *normal.hash();
+    let interop_hash = *interop.hash();
+
+    let gas_limit = 1_000_000;
+    let chain_spec = Arc::new(OpChainSpecBuilder::base_mainnet().regolith_activated().build());
+
+    // One shared handle drives every build, mirroring the single failsafe threaded through node
+    // setup; toggling it is what flips the gate, not building a fresh config each time.
+    let failsafe = InteropFailsafe::default();
+    let build = |failsafe: &InteropFailsafe| {
+        let mut ctx = payload_builder_ctx(chain_spec.clone(), gas_limit);
+        ctx.builder_config.interop_failsafe = failsafe.clone();
+        let (_info, included) = run_execute_best_transactions_with_ctx(
+            ctx,
+            signer,
+            vec![normal.clone(), interop.clone()],
+            None,
+            None,
+        );
+        included
+    };
+
+    // Failsafe off: both the normal and the interop tx are included.
+    failsafe.set(false);
+    assert_eq!(build(&failsafe), vec![normal_hash, interop_hash]);
+
+    // Failsafe on: the interop tx is excluded (marked invalid), the normal tx is still included.
+    failsafe.set(true);
+    assert_eq!(build(&failsafe), vec![normal_hash]);
+
+    // Failsafe cleared again: the same interop tx is included once more, confirming the previous
+    // build's `mark_invalid` did not permanently exclude it.
+    failsafe.set(false);
+    assert_eq!(build(&failsafe), vec![normal_hash, interop_hash]);
+}

rust/op-reth/crates/payload/src/config.rs

@@ -1,5 +1,6 @@
 //! Additional configuration for the OP builder
 
+use reth_optimism_txpool::interop::InteropFailsafe;
 use std::sync::{
     Arc,
     atomic::{AtomicBool, AtomicU64, Ordering},
@@ -14,6 +15,9 @@ pub struct OpBuilderConfig {
     pub gas_limit_config: OpGasLimitConfig,
     /// Local SDM `PostExec` production opt-in. Shared with the admin RPC.
     pub sdm_post_exec_opt_in: SdmPostExecOptIn,
+    /// Interop failsafe gate. Set by the interop filter client; read by the builder to exclude
+    /// interop txs from blocks while it is enabled.
+    pub interop_failsafe: InteropFailsafe,
     /// Maximum cumulative uncompressed (EIP-2718 encoded) block size in bytes.
     ///
     /// `None` disables the limit (the historical behavior). When set, the payload builder stops
@@ -32,6 +36,7 @@ impl OpBuilderConfig {
             da_config,
             gas_limit_config,
             sdm_post_exec_opt_in: SdmPostExecOptIn::default(),
+            interop_failsafe: InteropFailsafe::default(),
             max_uncompressed_block_size: None,
         }
     }

rust/op-reth/crates/txpool/src/interop.rs

@@ -1,15 +1,19 @@
 //! Additional support for pooled interop transactions.
 
 use alloy_consensus::Transaction;
-use reth_transaction_pool::PoolTransaction;
+use std::sync::{
+    Arc,
+    atomic::{AtomicBool, Ordering},
+};
 
 use crate::interop_filter::CROSS_L2_INBOX_ADDRESS;
 
-/// Returns true if the transaction's access list targets `CROSS_L2_INBOX_ADDRESS`
-/// with at least one storage key.
-pub(crate) fn is_interop_tx<T>(tx: &T) -> bool
+/// Returns true if the transaction's access list targets `CROSS_L2_INBOX_ADDRESS` with at least
+/// one storage key. Detection is intrinsic to the tx, so it also catches interop txs that never
+/// went through interop validation (e.g. private or locally-submitted txs).
+pub fn is_interop_tx<T>(tx: &T) -> bool
 where
-    T: PoolTransaction + Transaction,
+    T: Transaction,
 {
     tx.access_list()
         .map(|al| {
@@ -19,6 +23,26 @@ where
         .unwrap_or(false)
 }
 
+/// Shareable interop failsafe gate. The interop filter client writes it; the payload builder reads
+/// it to exclude interop txs while it is enabled. Cloning shares the flag, so one handle keeps the
+/// writer and reader in sync.
+#[derive(Debug, Clone, Default)]
+pub struct InteropFailsafe {
+    inner: Arc<AtomicBool>,
+}
+
+impl InteropFailsafe {
+    /// Returns the current failsafe state.
+    pub fn enabled(&self) -> bool {
+        self.inner.load(Ordering::Acquire)
+    }
+
+    /// Sets the failsafe state.
+    pub fn set(&self, enabled: bool) {
+        self.inner.store(enabled, Ordering::Release);
+    }
+}
+
 /// Helper trait that allows attaching an interop deadline.
 pub trait MaybeInteropTransaction {
     /// Attach an interop deadline