Home

Engine API Operations (External Interface)

7 min read

The Engine API serves as the primary coordination interface between the Consensus Layer (CL) and the Execution Layer (EL). It functions as a deterministic state transition mechanism where the CL directs the EL to update its view of the chain, build new blocks, or validate payloads received from the network.

Core API Endpoints for Block Building and Validation

The protocol utilizes several specific endpoints to manage the block lifecycle:

1. engine_forkchoiceUpdated (FCU)

This is the primary coordination method used by the Consensus Layer (CL) to update the Execution Layer’s (EL) view of the chain and, optionally, trigger the block production lifecycle.

  • Canonical Input:
    • ForkchoiceStateV1: Contains HeadBlockHash, SafeBlockHash, and FinalizedBlockHash.
    • PayloadAttributes: (Optional) Includes Timestamp, Random (prevrandao), SuggestedFeeRecipient, and OP Stack extensions like Transactions (forced L1 deposits), GasLimit, and EIP1559Params.
  • Canonical Output: engine.ForkChoiceResponse: Contains a PayloadStatusV1 and an 8-byte PayloadID if attributes were provided.
  • Logical Flow:
    1. Head Update: The EL updates its local head; if the block is unknown, it triggers a BeaconSync to fetch missing headers from peers.
    2. Validation: The EL performs Optimism-specific checks, such as requiring a GasLimit and ensuring Withdrawals are empty post-Canyon.
    3. ID Generation: A unique PayloadID is generated by hashing the attributes and the ParentHash.
    4. Miner Activation: If the ID is new, the EL triggers the Miner to start a background job constructing a block on the new head.

2. engine_getPayload

This endpoint is used by the CL to retrieve a built block once the construction process initiated by FCU is complete.

  • Canonical Input: PayloadID: The identifier returned by the previous FCU call.
  • Canonical Output: ExecutionPayloadEnvelope: Contains the ExecutionPayload (the executable block), blockValue (total fees), BlobsBundle (for EIP-4844), and Requests (for Prague).
  • Logical Flow:
    1. Interrupt: The EL sends a commitInterruptResolve signal to the background builder to stop filling the block with transactions.
    2. Finalization: The Miner stops the filling loop, finalizes the StateDB, and computes the final stateRoot and receipt roots.
    3. Assembly: The EL bundles the block data and calculated fees into an envelope and delivers it to the CL.

3. engine_newPayload

This endpoint is used for block validation when a node receives a pre-built payload from the network.

  • Canonical Input:
    • ExecutionPayload: The executable block data.
    • versionedHashes: (Post-Cancun) A list of blob hashes.
    • beaconRoot: (Post-Cancun) The parent beacon block root.
  • Canonical Output: PayloadStatusV1: Contains the status (VALID, INVALID, ACCEPTED, or SYNCING) and the LatestValidHash.
  • Logical Flow:
    1. Conversion: The EL converts the ExecutableData into a local Block object.
    2. Sanity Checks: It verifies the timestamp is strictly greater than the parent’s and checks OP-specific fields like WithdrawalsRoot.
    3. State Reconstruction: The EL re-executes every transaction in the payload using its local StateProcessor.
    4. Verification: It compares its locally computed stateRoot and receiptRoot against the values in the header. If they match, the block is marked VALID.

4. engine_signalSuperchainV1

An Optimism-specific endpoint used to manage protocol versioning and compatibility across the Superchain.

  • Canonical Input: SuperchainSignal: Contains the Recommended and Required protocol versions.
  • Canonical Output: Local ProtocolVersion: The version the node is currently running.
  • Logical Flow:
    1. Version Comparison: The EL compares its local version against the required version in the signal to determine if it is Ahead, Matching, or Outdated.
    2. Halt Policy: If the local version is OutdatedMajor and the node is configured to do so, it will shut down (halt) to prevent processing state transitions that may be incompatible with the rest of the Superchain.

5. engine_exchangeTransitionConfigurationV1

This method ensures that the CL and EL are synchronized regarding the transition from Proof-of-Work to Proof-of-Stake.

  • Canonical Input: TransitionConfigurationV1: Contains the Terminal Total Difficulty (TTD), TerminalBlockHash, and TerminalBlockNumber.
  • Canonical Output: TransitionConfigurationV1: The EL’s local configuration to confirm a match.
  • Logical Flow:
    1. TTD Verification: The EL confirms that the TTD provided by the CL matches its local settings.
    2. Status Sync: This exchange confirms both layers are ready for the Paris (The Merge) transition rules.

Logic in Action: The Payload Building Lifecycle

In the OP Stack, the Payload Building Lifecycle is a deterministic process where the Execution Layer (EL) shifts from a passive observer of the chain to an active producer of new state transitions. This process is orchestrated by the Consensus Layer (CL) using the Engine API to ensure that L2 blocks are built according to rollup-specific constraints like forced L1 deposits and Data Availability (DA) limits.

Phase 1: Initiation and Validation

The lifecycle begins when the CL sends an engine_forkchoiceUpdated (FCU) call to the EL containing payloadAttributes.

  • Rollup-Specific Validation: Before building starts, the EL validates the attributes against the active hard fork rules. It ensures a GasLimit is provided, confirms that Withdrawals are empty if the Canyon fork is active, and validates EIP1559Params for the Holocene fork.
  • PayloadID Generation: The EL prepares a BuildPayloadArgs object, which includes standard fields and Optimism extensions like the NoTxPool flag and forced Transactions. This object is hashed to create a unique 8-byte PayloadID, which acts as the identifier for the background building job.
  • Miner Activation: The EL triggers the Miner to start construction on top of the newly updated head block.

Phase 2: Environment and Preparation

The Miner sets up a new environment to represent the pending block state.

  • Fee and Gas Setup: The miner calculates the next Base Fee based on the parent’s gas usage and sets the target gas limit.
  • Jovian DA Footprint (Jovian Fork): If the Jovian fork is active, the miner extracts the daFootprintGasScalar from the first transaction in the block (the L1 Attributes deposit). This scalar is used to meter the “weight” of transactions based on the cost of posting their data to Layer 1.

Phase 3: Initial Block Construction

The miner first processes the essential rollup transactions before looking at the general transaction pool.

  • Forced Inclusions: Any transactions provided directly in the payloadAttributes (typically L1-to-L2 deposit transactions) are committed to the state immediately.
  • Immediate Availability: This “base” version of the block is stored in the Payload object as the empty version, ensuring that even if the building process is interrupted, the node can still deliver a valid block containing the required protocol transactions.

Phase 4: The Proactive Filling Loop

Unless the NoTxPool flag is set to true, the miner enters a background loop to maximize the block’s value by pulling transactions from the txpool.

  • Selection and Ordering: Transactions are pulled from the pool and sorted by effective miner gas tip and nonce.
  • Constraint Checks: Each transaction must pass several filters:
    • Execution Gas: Does it fit in the remaining block Gas Limit?.
    • Block Size: Does it exceed the protocol-level maximum block size (minus a buffer zone)?.
    • DA Limit (Jovian Logic): The miner calculates the transaction’s DA footprint (EstimatedDASize * Scalar). If adding the transaction would exceed the MaxDABlockSize, the miner stops adding transactions, even if execution gas is still available.
  • Background Updates: Every few seconds (governed by the Recommit interval), the miner restarts this loop to incorporate new, higher-paying transactions that have entered the mempool.

Phase 5: Finalization and Retrieval

When the block’s slot time arrives, the CL retrieves the completed payload.

  • The Retrieval Call: The CL invokes engine_getPayload with the specific PayloadID.
  • Interruption: This call sends a commitInterruptResolve signal to the background worker. The miner immediately stops adding transactions to prevent further state mutations.
  • Assembly: The miner finalizes the StateDB, computes the final stateRoot, assembles the logs, and bundles the transactions into a completed Block.
  • Envelope Delivery: The EL returns an ExecutionPayloadEnvelope containing the block data, total miner fees, and any necessary blob sidecars for EIP-4844.

The coordination between the Consensus Layer (CL) and Execution Layer (EL) in the OP Stack is governed by the Engine API, which provides the protocol-level endpoints necessary for the state transition function.

Graph View

Backlinks