feat: L2→L1→L2 synchronous composability

[AnshuJalan]

Summary

• End-to-end L2→L1→L2 pipeline for L2Direct UserOps: L2 outbound pre-simulation, L1 callback simulation with state_override, return signal injection into anchor, calldata patching for flash-loan-style apps
• Deferred-finalization multicall shape: [user_ops, tentativePropose, l1_calls, finalizePropose] when required return signals are present
• All contract addresses from env (no auto-derivation); consolidated L2_BRIDGE_ADDRESS as single env var

New env vars

• L1_SIGNAL_SERVICE_ADDRESS — L1 SignalService (for callback simulation state override)
• L2_SIGNAL_SERVICE_ADDRESS — L2 SignalService
• L2_BRIDGE_ADDRESS — replaces TAIKO_BRIDGE_L2_ADDRESS (used by both common config and realtime)

Depends on

• NethermindEth/surge-taiko-mono feat/l2-to-l1-to-l2-sync (tentativePropose/finalizePropose, ProposeInputV2, flash loan contracts)

Test plan

• Deploy protocol contracts (RealTimeInbox with tentativePropose/finalizePropose) on devnet
• Set all bridge/signal-service env vars
• Submit L2Direct flash loan UserOp via surge_sendUserOp
• Verify multicall trace: tentativePropose → processMessage → finalizePropose
• Verify L2 block includes return signal in anchor fast signals
• Verify existing L1→L2→L1 UserOp flow is unaffected

🤖 Generated with Claude Code

[mskrzypkows]

@claude

[claude]

Claude finished @mskrzypkows's task in 2m 23s —— View job

---

Code Review

• Gather context and read changed files
• Review common/src/config/mod.rs
• Review realtime/src/l1/ changes (bindings, config, execution_layer, proposal_tx_builder)
• Review realtime/src/l2/ changes (execution_layer, taiko)
• Review realtime/src/node/proposal_manager/ changes
• Review realtime/src/utils/config.rs
• Summarize findings

---

Summary

The PR implements a complete L2→L1→L2 synchronous composability pipeline. The overall architecture — pre-simulation on L2, state-override-based L1 callback simulation, calldata patching, and the deferred tentativePropose/finalizePropose multicall shape — is sound and well-structured. A few issues need attention before merge.

---

🔴 Critical Issues

1. .unwrap() in build_propose_blob will fail CI lint

realtime/src/l1/proposal_tx_builder.rs:122:

.input(inbox_calls.into_iter().next().unwrap().data.into())

The workspace enforces unwrap_used = "deny". This will fail cargo clippy. Needs to be replaced with ? or an explicit .ok_or_else(...).

Fix this →

---

2. Hardcoded storage slot 253 for _receivedSignals

realtime/src/l1/execution_layer.rs:423:

let received_signals_base_slot = U256::from(253u64);

This is a magic number tied to the Surge SignalService storage layout. If the contract is upgraded or the layout changes, the state override will silently compute the wrong slot — causing simulation to either always succeed (if slot happens to be non-zero) or always fail (if not). This should be:

• Derived on-chain via a getSignalSlot view function if available, or
• At minimum documented clearly with a link to the exact contract/layout file and a version pin

---

🟡 Medium Issues

3. Code duplication: two identical log-collection helpers

collect_logs_from_frame in realtime/src/l2/execution_layer.rs:589 is a near-duplicate of collect_logs_recursive in realtime/src/l1/execution_layer.rs:261. Both walk a CallFrame tree collecting CallLogFrames. This should live in a shared utility module.

Fix this →

---

4. _signal_slot_proof parameter is dead code

realtime/src/l1/execution_layer.rs:378:

async fn simulate_l1_callback_return_signal(
    &self,
    message_from_l2: Message,
    _signal_slot_proof: Bytes,   // ← never used
    ...

The parameter exists in the trait signature but is never used in the implementation — state override is used instead. Either remove it from the trait/impl or document why it's kept (e.g., "reserved for non-override fallback path").

---

5. New addresses missing from startup log

realtime/src/utils/config.rs:97-110: The Display impl for RealtimeConfig does not print signal_service or l2_signal_service. These are now required env vars; logging them on startup is important for debugging misconfigured deployments.

---

6. Signal slot invariant not validated

realtime/src/l1/proposal_tx_builder.rs:296-303: In the deferred flow, existing_signals is computed by filtering required_return_signals out of batch.signal_slots. If a required_return_signal is not present in batch.signal_slots, it silently disappears from existing_signals but is still included in ProposeInputV2.requiredReturnSignals. However, more importantly: the L2 anchor will only contain slots that were pushed into anchor_signal_slots. If a return slot is in requiredReturnSignals but not in the anchor's fast signals, the L2 block will succeed but finalizePropose on L1 may revert (or vice versa). A debug assertion here would help catch this during development:

debug_assert!(
    required_return_signals.iter().all(|s| batch.signal_slots.contains(s)),
    "required_return_signal not found in batch.signal_slots"
);

---

🟢 Minor / Nitpicks

7. POC comment signals incomplete implementation

realtime/src/l2/execution_layer.rs:569:

break; // first MessageSent wins for the POC

If a UserOp emits multiple MessageSent events (e.g., batched bridge calls), only the first is captured. This should be tracked as a known limitation or issue.

---

8. hex_encode reimplements hex::encode

realtime/src/node/proposal_manager/mod.rs:747-753:

fn hex_encode(bytes: &[u8]) -> String { ... }

The hex crate is already available (used in taiko.rs). Use hex::encode(bytes) directly and remove the local reimplementation.

Fix this →

---

9. Unreachable code path comment

realtime/src/l1/proposal_tx_builder.rs:114-127:

if batch.user_ops.is_empty() && batch.l1_calls.is_empty() {
    if inbox_calls.len() == 1 {

When use_deferred is true, inbox_calls.len() == 2. The comment says "Otherwise fall through to multicall assembly" but with an empty user_ops+l1_calls in deferred mode, the multicall would contain only [tentativePropose, finalizePropose] — no user ops or L1 calls. This is a degenerate case unlikely to occur in practice (you wouldn't use deferred if there are no L1 calls), but it could silently do something unexpected. An explicit guard or comment would help.

---

Architectural Notes

• The state-override simulation approach for _receivedSignals is clever but couples the implementation tightly to the SignalService storage layout. Consider making the storage slot configurable via env var as a short-term safety valve.
• The pending_return_signal field on BatchManager is a form of intra-call state transfer between add_pending_user_ops_to_draft_block and add_draft_block_to_proposal. The .take() on line 498 is correct (clears after use). Consider a local variable + explicit pass instead to make the data flow more visible.
• The fallback-to-classic behavior on simulation failure (line 400-406 in bridge_handler.rs) is a good defensive choice for a PoC.

[mikhailUshakoff]

We can’t rename that constant because it would interfere with our running nodes and require changes to our infrastructure, so it should be done in a separate PR