Operator TX — 实现

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: 将 Oracle 价格注入方式从 bootloader 内存 slot 改为 operator 合成 L2 交易注入，完成 Oracle E2E 闭环。

Architecture: State Keeper 在每个 batch 开始时构造一笔 operator → OracleHub 的合成 L2Tx（仿照 ProtocolUpgradeTx 模式），替代 bootloader memory slot 方式。完全移除旧的 bootloader Oracle 代码，OracleHub 权限从 onlyCallFromBootloader 改为 onlyOperator。

Tech Stack: Rust (era-core 200+ crates), Solidity (bootloader.yul + OracleHub.sol), Foundry (合约测试)

Design Doc: docs/plans/2026-03-04-oracle-operator-tx-design.md

Task 1: oracle_tx.rs 交易构造 + 单元测试

Files:

Create: era-core/core/node/state_keeper/src/oracle_tx.rs
Modify: era-core/core/node/state_keeper/src/lib.rs:17 (add module)

Step 1: Create oracle_tx.rs with build function + tests

Create era-core/core/node/state_keeper/src/oracle_tx.rs:

//! Oracle transaction builder — constructs synthetic L2Tx for price updates.
//!
//! The State Keeper calls `build_oracle_update_tx()` at the start of each batch
//! to inject Oracle price data as the first user-space transaction, immediately
//! after any protocol upgrade tx.

use zksync_contracts::ORACLE_HUB_ADDRESS;
use zksync_types::{
    fee::Fee, l2::L2Tx, Address, Nonce, L1BatchNumber, U256,
    transaction_request::PaymasterParams,
};

/// Gas limit for the Oracle update transaction.
/// Generous limit — operator doesn't actually pay gas.
const ORACLE_TX_GAS_LIMIT: u64 = 5_000_000;

/// Build an Oracle price update transaction.
///
/// Returns a `Transaction` that calls `OracleHub.batchUpdatePrices()` with the
/// pre-encoded ABI calldata from the Oracle service.
///
/// The transaction uses L2Tx type (EIP-712) with:
/// - sender: operator (fee_account)
/// - target: ORACLE_HUB_ADDRESS (0x8016)
/// - calldata: pre-encoded batchUpdatePrices(bytes32[],uint128[],uint64[],uint8[])
/// - gas_limit: 5M (operator doesn't pay)
/// - nonce: Nonce(0) — operator tx, not validated by mempool
pub fn build_oracle_update_tx(
    operator_address: Address,
    oracle_calldata: Vec<u8>,
) -> zksync_types::Transaction {
    let l2_tx = L2Tx::new(
        Some(ORACLE_HUB_ADDRESS),          // to: OracleHub (0x8016)
        oracle_calldata,                     // calldata: batchUpdatePrices(...)
        Nonce(0),                            // nonce: operator tx, not validated
        Fee {
            gas_limit: U256::from(ORACLE_TX_GAS_LIMIT),
            max_fee_per_gas: U256::from(0u64),
            max_priority_fee_per_gas: U256::from(0u64),
            gas_per_pubdata_limit: U256::from(800u64),
        },
        operator_address,                    // from: operator
        U256::zero(),                        // value: 0
        vec![],                              // factory_deps: none
        PaymasterParams::default(),          // no paymaster
    );

    l2_tx.into()
}

#[cfg(test)]
mod tests {
    use super::*;
    use zksync_types::ExecuteTransactionCommon;

    #[test]
    fn test_build_oracle_tx_correct_target() {
        let operator = Address::repeat_byte(0xAA);
        let calldata = vec![0x01, 0x02, 0x03, 0x04];

        let tx = build_oracle_update_tx(operator, calldata);

        assert_eq!(
            tx.execute.contract_address,
            Some(ORACLE_HUB_ADDRESS),
            "Oracle tx must target OracleHub (0x8016)"
        );
    }

    #[test]
    fn test_build_oracle_tx_correct_sender() {
        let operator = Address::repeat_byte(0xBB);
        let calldata = vec![0xDE, 0xAD];

        let tx = build_oracle_update_tx(operator, calldata.clone());

        match &tx.common_data {
            ExecuteTransactionCommon::L2(data) => {
                assert_eq!(data.initiator_address, operator);
            }
            _ => panic!("Oracle tx must be L2 type"),
        }
    }

    #[test]
    fn test_build_oracle_tx_correct_calldata() {
        let operator = Address::repeat_byte(0xCC);
        let calldata = vec![0xAA, 0xBB, 0xCC, 0xDD, 0xEE];

        let tx = build_oracle_update_tx(operator, calldata.clone());

        assert_eq!(tx.execute.calldata, calldata);
    }

    #[test]
    fn test_build_oracle_tx_zero_value() {
        let operator = Address::repeat_byte(0xDD);
        let calldata = vec![0x01];

        let tx = build_oracle_update_tx(operator, calldata);

        assert_eq!(tx.execute.value, U256::zero());
    }

    #[test]
    fn test_build_oracle_tx_gas_limit() {
        let operator = Address::repeat_byte(0xEE);
        let calldata = vec![0x01];

        let tx = build_oracle_update_tx(operator, calldata);

        match &tx.common_data {
            ExecuteTransactionCommon::L2(data) => {
                assert_eq!(data.fee.gas_limit, U256::from(ORACLE_TX_GAS_LIMIT));
            }
            _ => panic!("Oracle tx must be L2 type"),
        }
    }

    #[test]
    fn test_build_oracle_tx_large_calldata() {
        let operator = Address::repeat_byte(0xFF);
        // 100 pairs × ~128 bytes = ~12800 bytes — far exceeds old 768 byte limit
        let calldata = vec![0x42; 12800];

        let tx = build_oracle_update_tx(operator, calldata.clone());

        assert_eq!(tx.execute.calldata.len(), 12800);
        assert_eq!(tx.execute.calldata, calldata);
    }
}

Step 2: Register module in lib.rs

Modify era-core/core/node/state_keeper/src/lib.rs — add pub mod oracle_tx; after line 16 (pub mod io;):

pub mod executor;
mod health;
pub mod io;
mod keeper;
mod mempool_actor;
pub(crate) mod mempool_guard;
pub mod metrics;
pub mod node;
pub mod oracle_tx;    // ← ADD THIS LINE
pub mod seal_criteria;

Step 3: Verify compilation

Run: cd /Users/judybaby/CodeBase/github/Layer2/era-core/core && cargo check -p zksync_state_keeper 2>&1 | tail -5 Expected: compilation succeeds

Step 4: Run tests

Run: cd /Users/judybaby/CodeBase/github/Layer2/era-core/core && cargo test -p zksync_state_keeper oracle_tx -- --nocapture 2>&1 | tail -20 Expected: 6 tests pass

Step 5: Commit

cd /Users/judybaby/CodeBase/github/Layer2
git add era-core/core/node/state_keeper/src/oracle_tx.rs era-core/core/node/state_keeper/src/lib.rs
git commit -m "feat: oracle_tx.rs — synthetic L2Tx builder for Oracle price injection"

Task 2: MempoolIO 接入 SharedOracleService

Files:

Modify: era-core/core/node/state_keeper/src/io/mempool.rs:55-75 (add field)
Modify: era-core/core/node/state_keeper/src/io/mempool.rs:499-532 (constructor)
Modify: era-core/core/node/state_keeper/src/io/mempool.rs:580 (unsealed batch)
Modify: era-core/core/node/state_keeper/src/io/mempool.rs:710 (new batch)

Step 1: Add SharedOracleService import and field to MempoolIO

Add import at top of mempool.rs (after existing imports):

use baby_oracle_wiring::wiring::SharedOracleService;

Add field to MempoolIO struct (after settlement_layer at line 74):

pub struct MempoolIO {
    // ... existing fields ...
    settlement_layer: Option<SettlementLayer>,
    /// BabyDriver: Shared Oracle service for price data injection.
    oracle_service: Option<SharedOracleService>,
}

Step 2: Update constructor to accept oracle_service

Modify MempoolIO::new() at line 499:

    pub fn new(
        mempool: MempoolGuard,
        batch_fee_input_provider: Arc<dyn BatchFeeModelInputProvider>,
        pool: ConnectionPool<Core>,
        config: &StateKeeperConfig,
        fee_account: Address,
        delay_interval: Duration,
        chain_id: L2ChainId,
        l2_da_validator_address: Option<Address>,
        pubdata_type: PubdataType,
        settlement_layer: Option<SettlementLayer>,
        oracle_service: Option<SharedOracleService>,   // ← ADD
    ) -> anyhow::Result<Self> {
        Ok(Self {
            // ... existing fields unchanged ...
            settlement_layer,
            oracle_service,   // ← ADD
        })
    }

Step 3: Wire oracle_calldata into L1BatchParams construction

Replace oracle_calldata: None at line 580 (unsealed batch) with:

oracle_calldata: self.get_oracle_calldata(),

Replace oracle_calldata: None at line 710 (new batch) with:

oracle_calldata: self.get_oracle_calldata(),

Step 4: Add helper method to MempoolIO

Add to the impl MempoolIO block at line 734:

    /// Get Oracle calldata from the shared service.
    /// Returns None if Oracle is not configured or has no price data.
    fn get_oracle_calldata(&self) -> Option<Vec<u8>> {
        let service = self.oracle_service.as_ref()?;
        let svc = service.lock().ok()?;
        svc.encode_oracle_calldata()
    }

Step 5: Add baby_oracle_wiring dependency to state_keeper Cargo.toml

Check if baby_oracle_wiring is already a dependency:

Run: grep baby_oracle_wiring era-core/core/node/state_keeper/Cargo.toml

If not present, add to [dependencies] section:

baby_oracle_wiring = { path = "../../../../baby-modules/oracle-wiring" }

Note: If the crate path differs, search for existing usages: Run: grep -r baby_oracle_wiring era-core/core/ --include="Cargo.toml" | head -5

Step 6: Find and update all callers of MempoolIO::new()

Search for call sites:

Run: cd /Users/judybaby/CodeBase/github/Layer2 && grep -rn "MempoolIO::new(" era-core/ --include="*.rs"

For each call site, add None (or the actual SharedOracleService) as the last argument. The primary caller is in the node wiring layer — it will need the actual service. Test callers should pass None.

Step 7: Verify compilation

Run: cd /Users/judybaby/CodeBase/github/Layer2/era-core/core && cargo check -p zksync_state_keeper 2>&1 | tail -10 Expected: compilation succeeds (may need to fix callers first)

Step 8: Commit

cd /Users/judybaby/CodeBase/github/Layer2
git add era-core/core/node/state_keeper/src/io/mempool.rs
git add era-core/core/node/state_keeper/Cargo.toml
# Add any caller files that were modified
git commit -m "feat: MempoolIO accepts SharedOracleService, wires oracle_calldata into batch params"

Task 3: keeper.rs Oracle tx 注入

Files:

Modify: era-core/core/node/state_keeper/src/keeper.rs:660-710 (add process_oracle_tx)
Modify: era-core/core/node/state_keeper/src/keeper.rs:909-949 (inject in process_block)
Modify: era-core/core/node/state_keeper/src/io/mod.rs:189 (trait extension)

Step 1: Add get_oracle_tx_calldata to StateKeeperIO trait

Add to the StateKeeperIO trait in io/mod.rs after load_batch_state_hash() (line 254):

    /// BabyDriver: Get Oracle calldata for the current batch.
    /// Returns None if Oracle is not configured or has no data.
    fn get_oracle_tx_calldata(&self) -> Option<Vec<u8>> {
        None // default impl: no Oracle
    }

Step 2: Implement in MempoolIO

Add to impl StateKeeperIO for MempoolIO block (after any existing method, around line 495):

    fn get_oracle_tx_calldata(&self) -> Option<Vec<u8>> {
        self.get_oracle_calldata()
    }

Step 3: Add process_oracle_tx method to StateKeeperInner

Add in keeper.rs after process_upgrade_tx() (after line 710):

    /// BabyDriver: Process the Oracle price update transaction.
    ///
    /// Similar to `process_upgrade_tx()`, but failure does NOT block the batch.
    /// Oracle tx is injected as the first (or second, after upgrade tx) transaction.
    async fn process_oracle_tx(
        &mut self,
        batch_executor: &mut dyn BatchExecutor<OwnedStorage>,
        updates_manager: &mut UpdatesManager,
        oracle_calldata: Vec<u8>,
    ) -> anyhow::Result<()> {
        use crate::oracle_tx::build_oracle_update_tx;

        let operator_address = updates_manager.l1_batch.fee_account;
        let tx = build_oracle_update_tx(operator_address, oracle_calldata);

        tracing::info!(
            "Injecting Oracle price update tx into batch {}",
            updates_manager.l1_batch.number
        );

        let (seal_resolution, exec_result) = self
            .process_one_tx(batch_executor, updates_manager, tx.clone())
            .await?;

        match &seal_resolution {
            SealResolution::NoSeal | SealResolution::IncludeAndSeal => {
                let TxExecutionResult::Success {
                    tx_result,
                    tx_metrics: tx_execution_metrics,
                    call_tracer_result,
                    ..
                } = exec_result
                else {
                    // Oracle tx rejected — warn but don't block batch
                    tracing::warn!("Oracle tx execution was not successful, skipping");
                    return Ok(());
                };

                if tx_result.result.is_failed() {
                    // Oracle tx reverted inside VM — warn but don't block batch
                    tracing::warn!(
                        "Oracle price update tx reverted: {:?}",
                        tx_result.result
                    );
                    return Ok(());
                }

                updates_manager.extend_from_executed_transaction(
                    tx,
                    *tx_result,
                    *tx_execution_metrics,
                    call_tracer_result,
                );

                tracing::info!("Oracle price update tx executed successfully");
            }
            SealResolution::ExcludeAndSeal => {
                tracing::warn!("Oracle tx caused ExcludeAndSeal, skipping");
            }
            SealResolution::Unexecutable(reason) => {
                tracing::warn!("Oracle tx is unexecutable: {reason}, skipping");
            }
        }

        Ok(())
    }

Step 4: Inject Oracle tx in process_block()

Modify process_block() in keeper.rs around line 921. The current code:

        if let Some(protocol_upgrade_tx) = state.protocol_upgrade_tx.take() {
            self.inner
                .process_upgrade_tx(batch_executor, updates_manager, protocol_upgrade_tx)
                .await?;
        } else {

Change to:

        if let Some(protocol_upgrade_tx) = state.protocol_upgrade_tx.take() {
            self.inner
                .process_upgrade_tx(batch_executor, updates_manager, protocol_upgrade_tx)
                .await?;
        }

        // BabyDriver: Inject Oracle price update tx after protocol upgrade tx
        // (or as the first tx if no upgrade). Failure does not block the batch.
        if updates_manager.pending_executed_transactions_len() <= 1 {
            // Only inject on the first block of the batch
            if let Some(oracle_calldata) = self.inner.io.get_oracle_tx_calldata() {
                if let Err(e) = self.inner
                    .process_oracle_tx(batch_executor, updates_manager, oracle_calldata)
                    .await
                {
                    tracing::warn!("Oracle tx injection failed: {e:#}, continuing batch");
                }
            }
        }

        if updates_manager.pending_executed_transactions_len() == 0 {
            // No upgrade tx AND no oracle tx (or both skipped)
            // Handle L2 block params for non-first block

IMPORTANT: The original else branch (lines 926-948) handles the case where there's no protocol_upgrade_tx. After restructuring, we need to keep that logic but adjust the flow. The key is:

Protocol upgrade tx (if any)
Oracle tx (if any)
L2 block params for non-first blocks
Fictive block check
User tx loop

The exact restructuring needs care to preserve the original control flow. Read the full process_block() method carefully and ensure:

set_l2_block_params is still called for non-first blocks
next_block_should_be_fictive logic is preserved
The oracle tx runs only on first call per batch

Step 5: Verify compilation

Run: cd /Users/judybaby/CodeBase/github/Layer2/era-core/core && cargo check -p zksync_state_keeper 2>&1 | tail -10 Expected: compilation succeeds

Step 6: Commit

cd /Users/judybaby/CodeBase/github/Layer2
git add era-core/core/node/state_keeper/src/keeper.rs
git add era-core/core/node/state_keeper/src/io/mod.rs
git commit -m "feat: keeper.rs injects Oracle tx at batch start (non-blocking)"

Task 4: 移除 Rust 旧代码 (oracle_calldata 通道)

Files to modify (remove oracle_calldata):

File

Line(s)

Change

era-core/core/lib/vm_interface/src/types/inputs/l1_batch_env.rs:27-31

Remove oracle_calldata field

era-core/core/lib/multivm/src/versions/vm_latest/bootloader/init.rs:15-19,52-91

Remove ORACLE constants + append_oracle_calldata()

era-core/core/node/state_keeper/src/io/mod.rs:130-131

Remove oracle_calldata from L1BatchParams

era-core/core/node/state_keeper/src/io/mod.rs:167-168

Remove l1_batch_env.oracle_calldata = ...

era-core/core/node/state_keeper/src/io/mempool.rs:580

Remove oracle_calldata: self.get_oracle_calldata() (set in Task 2)

era-core/core/node/state_keeper/src/io/mempool.rs:710

Same as above

era-core/core/lib/vm_executor/src/storage.rs:97-98