Flashblock Spec

[dmarzzz]

Description

Specification for Flashblocks aka sub-second preconfirmations queryable via existing eth json rpc standard.

Tests

none

Additional context

Did a public review

Metadata

none

[lewejahlil]

Not sure of the right folks, but can this be reviewed and merged please? @alfonso-op @mds1

[lewejahlil]

@ethereum-optimism/specs-reviewers @ethereum-optimism/security-reviewers please review
CC: @yashvardhan-kukreja @K-Ho

[Ethnical]

The CI fail with a trailing new line.

specs/protocol/flashblocks.md:1029:400 MD047/single-trailing-newline Files should end with a single newline character
error: Recipe `lint-specs-md-check` failed on line 20 with exit code 1

I think the last line should finish with a new line, but I am not sure worth trying to fix the CI.

[Ethnical]

Here, the **** are not correctly set

****where they are described as an external party that the Sequencer can request blocks from.

[Ethnical]

NIT:7‑day challenge window would be 3.5 days challenge window now on L1.

[Ethnical]

The formatting in this block is broken, miss some * to format correctly

[lewejahlil]

@dmarzzz this is ready to merge after addressing comments

[krofax]

Suggested change

	<!-- START doctoc generated TOC please keep comment here to allow auto update -->
	<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
	**Table of Contents**
	- [Abstract](#abstract)
	- [Prerequisites](#prerequisites)
	- [Motivation](#motivation)
	- [Specification](#specification)
	- [Terminology](#terminology)
	- [Parameters](#parameters)
	- [Data structures](#data-structures)
	- [**`FlashblocksPayloadV1`**](#flashblockspayloadv1)
	- [**`ExecutionPayloadFlashblockDeltaV1`**](#executionpayloadflashblockdeltav1)
	- [**`ExecutionPayloadStaticV1`**](#executionpayloadstaticv1)
	- [**`Metadata`**](#metadata)
	- [**`AccountMetadata`**](#accountmetadata)
	- [**`StorageSlot`**](#storageslot)
	- [**`TransactionMetadata`**](#transactionmetadata)
	- [System architecture](#system-architecture)
	- [Out-of-Protocol Design](#out-of-protocol-design)
	- [In-Protocol vs. Out-of-Protocol](#in-protocol-vs-out-of-protocol)
	- [Design Rationale and Benefits](#design-rationale-and-benefits)
	- [Implications for This Specification](#implications-for-this-specification)
	- [Assumptions About Op Stack](#assumptions-about-op-stack)
	- [Flashblock Lifecycle](#flashblock-lifecycle)
	- [Flashblock Construction Process](#flashblock-construction-process)
	- [Handling of Sequencer Transactions](#handling-of-sequencer-transactions)
	- [Transaction Inclusion Heuristics](#transaction-inclusion-heuristics)
	- [Post-block Execution Rules](#post-block-execution-rules)
	- [Construction Steps](#construction-steps)
	- [Flashblocks Metadata](#flashblocks-metadata)
	- [Alternative Design Consideration](#alternative-design-consideration)
	- [Rationale for Including State Roots in Flashblocks](#rationale-for-including-state-roots-in-flashblocks)
	- [Non-Blocking Block Production](#non-blocking-block-production)
	- [Builder Availability and System Reliability](#builder-availability-and-system-reliability)
	- [Future Design Considerations](#future-design-considerations)
	- [Builder-to-Rollup-boost Communication Flow](#builder-to-rollup-boost-communication-flow)
	- [Flashblock Validity Rules](#flashblock-validity-rules)
	- [Flashblock System Invariants](#flashblock-system-invariants)
	- [Flashblock Propagation](#flashblock-propagation)
	- [Secure propagation](#secure-propagation)
	- [Flashblock JSON-RPC APIs](#flashblock-json-rpc-apis)
	- [Ethereum JSON RPC Modifications](#ethereum-json-rpc-modifications)
	- [op_supportedCapabilities](#op_supportedcapabilities)
	- [Reliability and Operational Considerations](#reliability-and-operational-considerations)
	- [Transaction Propagation](#transaction-propagation)
	- [Failover scenarios](#failover-scenarios)
	- [Block Builder](#block-builder)
	- [The Sequencer or Rollup-boost](#the-sequencer-or-rollup-boost)
	- [Integration with High Availability Sequencer Setups](#integration-with-high-availability-sequencer-setups)
	- [Faults](#faults)
	- [**Safety Faults**](#safety-faults)
	- [**Liveness Faults**](#liveness-faults)
	- [Rationale](#rationale)
	- [Why out-of-protocol](#why-out-of-protocol)
	- [Why not shorter block times](#why-not-shorter-block-times)
	- [Backwards Compatibility](#backwards-compatibility)
	- [End Users](#end-users)
	- [Infrastructure Operators](#infrastructure-operators)
	- [Implementation](#implementation)
	<!-- END doctoc generated TOC please keep comment here to allow auto update -->
	# Flashblocks
	<!-- START doctoc generated TOC please keep comment here to allow auto update -->
	<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
	**Table of Contents**
	- [Abstract](#abstract)
	- [Prerequisites](#prerequisites)
	- [Motivation](#motivation)
	- [Specification](#specification)
	- [Terminology](#terminology)
	- [Parameters](#parameters)
	- [Data structures](#data-structures)
	- [`FlashblocksPayloadV1`](#flashblockspayloadv1)
	- [`ExecutionPayloadFlashblockDeltaV1`](#executionpayloadflashblockdeltav1)
	- [`ExecutionPayloadStaticV1`](#executionpayloadstaticv1)
	- [`Metadata`](#metadata)
	- [`AccountMetadata`](#accountmetadata)
	- [`StorageSlot`](#storageslot)
	- [`TransactionMetadata`](#transactionmetadata)
	- [System architecture](#system-architecture)
	- [Out-of-Protocol Design](#out-of-protocol-design)
	- [In-Protocol vs. Out-of-Protocol](#in-protocol-vs-out-of-protocol)
	- [Design Rationale and Benefits](#design-rationale-and-benefits)
	- [Implications for This Specification](#implications-for-this-specification)
	- [Assumptions About Op Stack](#assumptions-about-op-stack)
	- [Flashblock Lifecycle](#flashblock-lifecycle)
	- [Flashblock Construction Process](#flashblock-construction-process)
	- [Handling of Sequencer Transactions](#handling-of-sequencer-transactions)
	- [Transaction Inclusion Heuristics](#transaction-inclusion-heuristics)
	- [Post-block Execution Rules](#post-block-execution-rules)
	- [Construction Steps](#construction-steps)
	- [Flashblocks Metadata](#flashblocks-metadata)
	- [Alternative Design Consideration](#alternative-design-consideration)
	- [Rationale for Including State Roots in Flashblocks](#rationale-for-including-state-roots-in-flashblocks)
	- [Non-Blocking Block Production](#non-blocking-block-production)
	- [Builder Availability and System Reliability](#builder-availability-and-system-reliability)
	- [Future Design Considerations](#future-design-considerations)
	- [Builder-to-Rollup-boost Communication Flow](#builder-to-rollup-boost-communication-flow)
	- [Flashblock Validity Rules](#flashblock-validity-rules)
	- [Flashblock System Invariants](#flashblock-system-invariants)
	- [Flashblock Propagation](#flashblock-propagation)
	- [Secure propagation](#secure-propagation)
	- [Flashblock JSON-RPC APIs](#flashblock-json-rpc-apis)
	- [Ethereum JSON RPC Modifications](#ethereum-json-rpc-modifications)
	- [op_supportedCapabilities](#op_supportedcapabilities)
	- [Reliability and Operational Considerations](#reliability-and-operational-considerations)
	- [Transaction Propagation](#transaction-propagation)
	- [Failover scenarios](#failover-scenarios)
	- [Block Builder](#block-builder)
	- [The Sequencer or Rollup-boost](#the-sequencer-or-rollup-boost)
	- [Integration with High Availability Sequencer Setups](#integration-with-high-availability-sequencer-setups)
	- [Faults](#faults)
	- [Safety Faults](#safety-faults)
	- [Liveness Faults](#liveness-faults)
	- [Rationale](#rationale)
	- [Why out-of-protocol](#why-out-of-protocol)
	- [Why not shorter block times](#why-not-shorter-block-times)
	- [Backwards Compatibility](#backwards-compatibility)
	- [End Users](#end-users)
	- [Infrastructure Operators](#infrastructure-operators)
	- [Implementation](#implementation)
	<!-- END doctoc generated TOC please keep comment here to allow auto update -->

[krofax]

Suggested change

	```python
	class FlashblocksPayloadV1():
	version: Bytes4
	payload_id: Bytes8
	parent_flash_hash: Optional[Bytes32]
	index: uint64
	static: Optional[ExecutionPayloadStaticV1]
	diff: ExecutionPayloadFlashblockDeltaV1
	metadata: FlashblocksMetadata
	**Field descriptions:**
	- `payload_id`: PayloadID is an identifier of the payload build process. The same for all flashblocks.
	- `index`: Index of the Flashblock within the parent block.
	- `parent_flash_hash`: SSZ hash of the parent flashblock in the sequence. For the first flashblock (index 0), the field
	is empty.
	- `base` *(Optional)*: Reference execution payload serving as the unchanging base configuration.
	- `diff`: Container with fields representing changes from the base payload.
	- `metadata`: Supplementary information about the execution of the flashblock. For example: account state changes,
	storage modifications, transaction receipts.
	### **`ExecutionPayloadFlashblockDeltaV1`**
	```python
	class FlashblocksPayloadV1():
	version: Bytes4
	payload_id: Bytes8
	parent_flash_hash: Optional[Bytes32]
	index: uint64
	static: Optional[ExecutionPayloadStaticV1]
	diff: ExecutionPayloadFlashblockDeltaV1
	metadata: FlashblocksMetadata

Field descriptions:

• payload_id: PayloadID is an identifier of the payload build process. The same for all flashblocks.
• index: Index of the Flashblock within the parent block.
• parent_flash_hash: SSZ hash of the parent flashblock in the sequence. For the first flashblock (index 0), the field
  is empty.
• base (Optional): Reference execution payload serving as the unchanging base configuration.
• diff: Container with fields representing changes from the base payload.
• metadata: Supplementary information about the execution of the flashblock. For example: account state changes,
  storage modifications, transaction receipts.

ExecutionPayloadFlashblockDeltaV1

[krofax]

Suggested change

	```python
	class FlashblockMetadata():
	accounts: List[AccountMetadata]
	transactions: List[TransactionMetadata]
	```python
	class FlashblockMetadata():
	accounts: List[AccountMetadata]
	transactions: List[TransactionMetadata]

[krofax]

Suggested change

	### **`AccountMetadata`**
	### AccountMetadata

[krofax]

Suggested change

	1. **Fork Choice Update**:
	The Sequencer initiates the block-building cycle by sending an `engine_forkchoiceUpdated` with attributes call to
	Rollup Boost as it normally would to its local Execution Engine.
	2. **Fork Choice Update Forwarding**:
	Rollup Boost forwards the `engine_forkchoiceUpdated` call concurrently to:
	[-*+] The Sequencer’s local Execution Engine
	[-*+] The External Block Builder
	3. **Flashblock Construction**:
	Upon receiving the fork choice update, the External Block Builder constructs and continuously delivers
	`FlashblocksPayloadV1` at intervals defined by `FLASHBLOCKS_TIME` following the **Flashblocks Construction Process**
	defined in this document.
	It's important to emphasize that during this process, the External Block Builder sends only the incremental changes
	in each Flashblock, not the full block state each time. Each `FlashblocksPayloadV1` contains just the delta from the
	previous state (new transactions, updated state roots, etc.), allowing for efficient bandwidth usage and faster
	propagation.
	Only the first Flashblock (with `index` 0) includes the `static` field containing immutable block data, while
	subsequent Flashblocks omit this field since this information remains constant throughout the block's construction.
	Each Flashblock includes a `parent_flash_hash` that references the SSZ hash of the previous Flashblock in the sequence,
	creating a hash-linked chain within the block.
	The combined information received across all flashblocks is sufficient to fully reconstruct the complete block
	without any additional data.
	4. **Flashblock Validation and Propagation**:
	For each received `FlashblocksPayloadV1`, Rollup Boost validates it against the Sequencer’s local Execution Engine
	and according to the **Flashblocks Validity Rules** defined in this document. Upon successful validation, Rollup Boost
	propagates the payload to all subscribed Flashblock-compatible RPC providers.
	5. **Preconfirmed State Updates**:
	Flashblock-compatible RPC providers insert validated payloads into their local Preconfirmed State Overlay,
	providing immediate preconfirmation states to end-users via Flashblock-enhanced Ethereum JSON-RPC endpoints.
	6. **Final L2 Block Delivery**:
	When the Sequencer calls `engine_getPayload`, Rollup Boost returns a single coherent block payload based on the
	validated Flashblocks received since the last fork choice update. Note that this does not require additional external
	requests or any last-minute processing.
	7. **Full Block Propagation**:
	The Sequencer propagates the aggregated block following standard OP Stack protocol rules.
	1. **Fork Choice Update**:
	The Sequencer initiates the block-building cycle by sending an `engine_forkchoiceUpdated` with attributes call to
	Rollup Boost as it normally would to its local Execution Engine.
	2. **Fork Choice Update Forwarding**:
	Rollup Boost forwards the `engine_forkchoiceUpdated` call concurrently to:
	- The Sequencer's local Execution Engine
	- The External Block Builder
	3. **Flashblock Construction**:
	Upon receiving the fork choice update, the External Block Builder constructs and continuously delivers
	`FlashblocksPayloadV1` at intervals defined by `FLASHBLOCKS_TIME` following the **Flashblocks Construction Process**
	defined in this document.
	It's important to emphasize that during this process, the External Block Builder sends only the incremental changes
	in each Flashblock, not the full block state each time. Each `FlashblocksPayloadV1` contains just the delta from the
	previous state (new transactions, updated state roots, etc.), allowing for efficient bandwidth usage and faster
	propagation.
	Only the first Flashblock (with `index` 0) includes the `static` field containing immutable block data, while
	subsequent Flashblocks omit this field since this information remains constant throughout the block's construction.
	Each Flashblock includes a `parent_flash_hash` that references the SSZ hash of the previous Flashblock in the sequence,
	creating a hash-linked chain within the block.
	The combined information received across all flashblocks is sufficient to fully reconstruct the complete block
	without any additional data.
	4. **Flashblock Validation and Propagation**:
	For each received `FlashblocksPayloadV1`, Rollup Boost validates it against the Sequencer's local Execution Engine
	and according to the **Flashblocks Validity Rules** defined in this document. Upon successful validation, Rollup Boost
	propagates the payload to all subscribed Flashblock-compatible RPC providers.
	5. **Preconfirmed State Updates**:
	Flashblock-compatible RPC providers insert validated payloads into their local Preconfirmed State Overlay,
	providing immediate preconfirmation states to end-users via Flashblock-enhanced Ethereum JSON-RPC endpoints.
	6. **Final L2 Block Delivery**:
	When the Sequencer calls `engine_getPayload`, Rollup Boost returns a single coherent block payload based on the
	validated Flashblocks received since the last fork choice update. Note that this does not require additional external
	requests or any last-minute processing.
	7. **Full Block Propagation**:
	The Sequencer propagates the aggregated block following standard OP Stack protocol rules.

[krofax]

Suggested change

	1. **Transaction Selection**
	- Retrieve transactions from local or external mempool:
	- Prioritize and sort transactions based on predefined sequencing policies, such as priority ordering or by MEV paid.
	2. **Transaction Execution**
	- Sequentially execute selected transactions against a state snapshot derived from the current execution payload base
	(ExecutionPayloadBaseV1) or the last validated flashblock
	- Apply the transaction inclusion heuristics described earlier to determine when to stop including transactions
	- After transaction execution completes, apply all post-block execution rules as described in the Post-Block Execution
	Rules section
	3. **Flashblock Payload Assembly**
	- After transaction execution, compute and record the following execution state updates:
	[-*+] `state_root`: The new post-execution state root resulting from the executed transactions.
	[-*+] `receipts_root`: The receipts trie root derived from execution outcomes.
	[-*+] `logs_bloom`: Aggregated logs bloom from all emitted transaction logs within this flashblock.
	[-*+] `gas_used`: Total gas consumed by executed transactions.
	[-*+] `transactions`: Serialized transaction payloads included within the flashblock.
	[-*+] `withdrawals` (if applicable): Withdrawals executed during the current flashblock interval (as per OP Stack
	withdrawal specification).
	[-*+] `block_hash`: Computed block hash uniquely identifying this flashblock execution state.
	Note that each flashblock builds upon the state of all previous flashblocks, with these fields reflecting the
	cumulative state after applying the new transactions in this particular flashblock.
	- Encapsulate these computed updates into `ExecutionPayloadFlashblockDeltaV1`.
	5. **Flashblock Indexing and Metadata**
	- Assign a monotonically incremented `index` to the newly constructed Flashblock payload.
	- Compute the SSZ hash of the previous Flashblock and assign it as the `parent_flash_hash` (for the first Flashblock
	with index 0, this field is empty)
	6. **Flashblock Delivery**
	- Package the `index`, `payload_id`, `ExecutionPayloadFlashblockDeltaV1`, and metadata into a `FlashblocksPayloadV1`
	payload.
	- Deliver the assembled `FlashblocksPayloadV1` payload promptly to Rollup Boost via the designated Flashblocks
	submission API.
	7. **Subsequent Flashblock Construction**
	- Immediately after successful delivery, increment the Flashblock `index`.
	- Revert any post-block execution changes as described in the Post-Block Execution Rules section
	- Reset the transaction execution context based on the newly delivered state.
	- Begin constructing the next `FlashblocksPayloadV1` payload, repeating from step 1 until a termination condition is
	reached (e.g., end of block building period via `engine_getPayload` request).
	8. **Flashblock Construction Termination**
	- Flashblock construction continues iteratively until:
	[-*+] Rollup Boost signals final block aggregation and propagation via `engine_getPayload`.
	[-*+] A failure or timeout condition arises requiring failover procedures, detailed separately.
	1. **Transaction Selection**
	- Retrieve transactions from local or external mempool:
	- Prioritize and sort transactions based on predefined sequencing policies, such as priority ordering or by MEV paid.
	2. **Transaction Execution**
	- Sequentially execute selected transactions against a state snapshot derived from the current execution payload base
	(ExecutionPayloadBaseV1) or the last validated flashblock
	- Apply the transaction inclusion heuristics described earlier to determine when to stop including transactions
	- After transaction execution completes, apply all post-block execution rules as described in the Post-Block Execution
	Rules section
	3. **Flashblock Payload Assembly**
	- After transaction execution, compute and record the following execution state updates:
	- `state_root`: The new post-execution state root resulting from the executed transactions.
	- `receipts_root`: The receipts trie root derived from execution outcomes.
	- `logs_bloom`: Aggregated logs bloom from all emitted transaction logs within this flashblock.
	- `gas_used`: Total gas consumed by executed transactions.
	- `transactions`: Serialized transaction payloads included within the flashblock.
	- `withdrawals` (if applicable): Withdrawals executed during the current flashblock interval (as per OP Stack
	withdrawal specification).
	- `block_hash`: Computed block hash uniquely identifying this flashblock execution state.
	Note that each flashblock builds upon the state of all previous flashblocks, with these fields reflecting the
	cumulative state after applying the new transactions in this particular flashblock.
	- Encapsulate these computed updates into `ExecutionPayloadFlashblockDeltaV1`.
	4. **Flashblock Indexing and Metadata**
	- Assign a monotonically incremented `index` to the newly constructed Flashblock payload.
	- Compute the SSZ hash of the previous Flashblock and assign it as the `parent_flash_hash` (for the first Flashblock
	with index 0, this field is empty)
	5. **Flashblock Delivery**
	- Package the `index`, `payload_id`, `ExecutionPayloadFlashblockDeltaV1`, and metadata into a `FlashblocksPayloadV1`
	payload.
	- Deliver the assembled `FlashblocksPayloadV1` payload promptly to Rollup Boost via the designated Flashblocks
	submission API.
	6. **Subsequent Flashblock Construction**
	- Immediately after successful delivery, increment the Flashblock `index`.
	- Revert any post-block execution changes as described in the Post-Block Execution Rules section
	- Reset the transaction execution context based on the newly delivered state.
	- Begin constructing the next `FlashblocksPayloadV1` payload, repeating from step 1 until a termination condition is
	reached (e.g., end of block building period via `engine_getPayload` request).
	7. **Flashblock Construction Termination**
	- Flashblock construction continues iteratively until:
	- Rollup Boost signals final block aggregation and propagation via `engine_getPayload`.
	- A failure or timeout condition arises requiring failover procedures, detailed separately.

[krofax]

Suggested change

	implementation [here](https://github.com/base/flashblocks-websocket-proxy).
	implementation in the [flashblocks-websocket-proxy repository](https://github.com/base/flashblocks-websocket-proxy).

[krofax]

@dmarzzz Please add this word.txt file in the PR.

addi
Airgap
airgap
altda
Basefee
basefee
basefeevault
basefeevaultconfig
bijective
bitlist
bitlists
BLOBBASEFEE
blobbasefee
blobdata
Blockhash
blockhash
blockheaders
blockquotes
Blockspace
blockspace
blocksv
blocktime
Bootnode
bridgeaddress
bytestring
calldatas
CALLVALUE
Celestia
celestia
cellborder
Chainid
chainid
checkpointed
clabby
codehash
Coef
configurables
CONFIGURATOR
Configurator
configurator
counterfactually
Crosschain
crosschain
crossdomainmessenger
crossdomainmessengeraddress
cryptoeconomic
cwia
datas
Decentralizable
delayedweth
DELEGATECALL
delegatecall
delegatecalls
delegatees
delegators
Dencun
Depositer
devnet
dialable
Discv
discv
disputegamefactory
Doubleword
EBADF
ecpairing
Edgington
eigenda
elif
errno
failovers
fanout
Fastlz
fastlz
feevault
feevaultconfig
Filecoin
FINDNODES
Flashblock
flashblock
Flashblock's
flashblock's
FLASHBLOCKS
Flashblocks
flashblocks
flashblocksv
flashbots
Forkchoice
forkchoice
FPAC
FPVM
FUTEX
Futex
futex
Futexes
gaspayingtoken
gaspayingtokenname
gaspayingtokensymbol
gaspriceoracle
gindex
griefed
Hardfork
hardfork
hardfork's
hardforks
hardfork’s
Holesky
idxs
IERC
impactfully
Impls
incentivized
initcode
Initializable
inputbytes
interchangable
invis
IPFS
IWANT
justfile
katex
keccack
Keccak
keccak
Libp
libp
linkcheck
mcache
MCOPY
mdbook
Mdiamond
Merkle
merkle
merkleized
meshsub
messagepasser
messsage
Mintable
mmap
mplex
Multicall
multiclient
multisignature
Multistream
multistream
mutliplex’ing
nanosleep
newrank
nodehash
noops
offchain
OPCM
opstack
outputroot
parseable
Pausability
Pectra
peerstore
PERMISSIONED
Permissioned
permissioned
Permissionless
permissionless
permissionlessly
Precommitments
Preconfirmation
preconfirmation
Preconfirmations
preconfirmations
Preconfirmed
preconfirmed
Predeploy
predeploy
Predeployed
predeployed
Predeploys
predeploys
Preimage
preimage
preimage's
preimages
Preinstalls
preinstalls
PRESTATE
Prestate
prestate
PREVRANDAO
protocolversion
protolambda
RANDAO
Randao
randao
rankdir
rbuilder
redeployments
rederiving
regenesis
remotechainid
replayability
replayable
reposted
returndata
Rollups
rollups
RPCN
runbooks
Sched
sched
secp
SELFDESTRUCT
sequencerfeevault
sequencerfeevaultconfig
Shapella
Singlethreaded
singlethreaded
SLOAD
Solana
standardbridge
standardbridgeaddress
statelessly
Subgame
subgame
Subgames
subgames
SUPC
Superchain
superchain
Superchain's
superfactory
syscall
Syscalls
syscalls
systemconfig
timelock
tlsv
triggerable
txdata
Typehash
typehash
unaliased
uncountered
unfinalized
Unichain
uniprocessor
unmetered
unsafeblocksigner
Unsubmitted
UPGRADER
upgrader
UPNP
usecase
userspace
uvarint
varint
wakeup
wighawag
yamux

[pcw109550]

Can we close this because #754 is merged?

[maurelian]

Closing as stale.