From ed664cbbd2bbdf11c4306afb47596ac17c26167f Mon Sep 17 00:00:00 2001 From: avalonche Date: Tue, 19 Aug 2025 05:22:16 +1000 Subject: [PATCH 1/8] docs scaffolding --- book/src/SUMMARY.md | 7 ++- book/src/architecture/overview.md | 71 ++++++++++++++++++++++++ book/src/block-building/basics.md | 1 + book/src/configuration/basic.md | 1 + book/src/flashblocks/introduction.md | 1 + book/src/getting-started/installation.md | 1 + book/src/intro.md | 37 ++++++++++++ book/theme/head.hbs | 6 +- 8 files changed, 123 insertions(+), 2 deletions(-) create mode 100644 book/src/architecture/overview.md create mode 100644 book/src/block-building/basics.md create mode 100644 book/src/configuration/basic.md create mode 100644 book/src/flashblocks/introduction.md create mode 100644 book/src/getting-started/installation.md create mode 100644 book/src/intro.md diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index 320aa2da..6cc78752 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -1,3 +1,8 @@ # Summary -- [Introduction](./README.md) \ No newline at end of file +- [Introduction](./intro.md) +- [Architecture Overview](./architecture/overview.md) +- [Getting Started](./getting-started/installation.md) +- [Configuration](./configuration/basic.md) +- [Block Building](./block-building/basics.md) +- [Flashblocks](./flashblocks/introduction.md) \ No newline at end of file diff --git a/book/src/architecture/overview.md b/book/src/architecture/overview.md new file mode 100644 index 00000000..2314676b --- /dev/null +++ b/book/src/architecture/overview.md @@ -0,0 +1,71 @@ +# Architecture Overview + +Rollup Boost modifies the workflow of the engine api to enable block building and flashblocks. + +## Core System Workflow + +1. `rollup-boost` receives an `engine_FCU` with the attributes to initiate block building: + - It relays the call to proposer `op-geth` as usual and multiplexes the call to builder. + - The FCU call returns the proposer payload id and internally maps the builder payload id to proposer payload id in the case the payload ids are not the same. +2. When `rollup-boost` receives an `engine_getPayload`: + - It queries proposer `op-geth` for a fallback block. + - In parallel, it queries builder for a block. +3. Upon receiving the builder block: + - `rollup-boost` validates the block with proposer `op-geth` using `engine_newPayload`. + - This validation ensures the block will be valid for proposer `op-geth`, preventing network stalls due to invalid blocks. + - If the external block is valid, it is returned to the proposer `op-node`. Otherwise, `rollup-boost` will return the fallback block. +4. The proposer `op-node` sends a `engine_newPayload` request to `rollup-boost` and another `engine_FCU` without attributes to update chain state. + - `rollup-boost` just relays the calls to proposer `op-geth`. + - Note that since we already called `engine_newPayload` on the proposer `op-geth` in the previous step, the block should be cached and add minimal latency. + - The builder `op-node` will receive blocks via p2p gossip and keep the builder node in sync via the engine api. + +```mermaid +sequenceDiagram + box Proposer + participant op-node + participant rollup-boost + participant op-geth + end + box Builder + participant builder-op-node as op-node + participant builder-op-geth as builder + end + + Note over op-node, builder-op-geth: 1. Triggering Block Building + op-node->>rollup-boost: engine_FCU (with attrs) + rollup-boost->>op-geth: engine_FCU (with attrs) + rollup-boost->>builder-op-geth: engine_FCU (with attrs) + rollup-boost->>op-node: proposer payload id + + Note over op-node, builder-op-geth: 2. Get Local and Builder Blocks + op-node->>rollup-boost: engine_getPayload + rollup-boost->>op-geth: engine_getPayload + rollup-boost->>builder-op-geth: engine_getPayload + + Note over op-node, builder-op-geth: 3. Validating and Returning Builder Block + rollup-boost->>op-geth: engine_newPayload + op-geth->>rollup-boost: block validity + rollup-boost->>op-node: block payload + + Note over op-node, builder-op-geth: 4. Updating Chain State + op-node->>rollup-boost: engine_newPayload + rollup-boost->>op-geth: engine_newPayload + op-node->>rollup-boost: engine_FCU (without attrs) + rollup-boost->>op-geth: engine_FCU (without attrs) +``` + +## RPC Calls + +By default, `rollup-boost` will proxy all RPC calls from the proposer `op-node` to its local `op-geth` node. These are the list of RPC calls that are proxied to both the proposer and the builder execution engines: + +- `engine_forkchoiceUpdatedV3`: this call is only multiplexed to the builder if the call contains payload attributes and the no_tx_pool attribute is false. +- `engine_getPayloadV3`: this is used to get the builder block. +- `miner_*`: this allows the builder to be aware of changes in effective gas price, extra data, and [DA throttling requests](https://docs.optimism.io/builders/chain-operators/configuration/batcher) from the batcher. +- `eth_sendRawTransaction*`: this forwards transactions the proposer receives to the builder for block building. This call may not come from the proposer `op-node`, but directly from the rollup's rpc engine. + +### Boost Sync + +By default, `rollup-boost` will sync the builder with the proposer `op-node`. After the builder is synced, boost sync improves the performance of keeping the builder in sync with the tip of the chainby removing the need to receive chain updates via p2p via the builder `op-node`. This entails additional engine api calls that are multiplexed to the builder from rollup-boost: + +- `engine_forkchoiceUpdatedV3`: this call will be multiplexed to the builder regardless of whether the call contains payload attributes or not. +- `engine_newPayloadV3`: ensures the builder has the latest block if the local payload was used. \ No newline at end of file diff --git a/book/src/block-building/basics.md b/book/src/block-building/basics.md new file mode 100644 index 00000000..17292419 --- /dev/null +++ b/book/src/block-building/basics.md @@ -0,0 +1 @@ +# Block Building diff --git a/book/src/configuration/basic.md b/book/src/configuration/basic.md new file mode 100644 index 00000000..a025a48b --- /dev/null +++ b/book/src/configuration/basic.md @@ -0,0 +1 @@ +# Configuration diff --git a/book/src/flashblocks/introduction.md b/book/src/flashblocks/introduction.md new file mode 100644 index 00000000..fb00e549 --- /dev/null +++ b/book/src/flashblocks/introduction.md @@ -0,0 +1 @@ +# Flashblocks diff --git a/book/src/getting-started/installation.md b/book/src/getting-started/installation.md new file mode 100644 index 00000000..bad55622 --- /dev/null +++ b/book/src/getting-started/installation.md @@ -0,0 +1 @@ +# Getting Started diff --git a/book/src/intro.md b/book/src/intro.md new file mode 100644 index 00000000..02c5d2cc --- /dev/null +++ b/book/src/intro.md @@ -0,0 +1,37 @@ +# Rollup Boost + +Rollup Boost is a lightweight sidecar for rollup to enable rollup extensions. These extensions allows for an efficient, decentralized and verifiable block building platform for rollups. + +## What is Rollup Boost? + +[Rollup Boost](https://github.com/flashbots/rollup-boost/) uses the [Engine API](https://specs.optimism.io/protocol/exec-engine.html#engine-api) in the Optimism stack to enable its rollup extensions. This requires no modification to the OP stack software and enable rollup operators to connect to an external builder. + +It is designed and developed by [Flashbots](https://flashbots.net/) under a MIT license. We invite developers, rollup operators, and researchers to join in developing this open-source software to achieve efficiency and decentralization in the rollup ecosystem. + +## What are the design goals of Rollup Boost? + +**Simplicity**: Rollup Boost was designed with minimal complexity and maintaining a lightweight setup avoids additional latency. By focusing on simplicity, Rollup Boost integrates smoothly into the OP stack without disrupting existing op-node and execution engine communication. + +**Modularity**: Recognizing that rollups have varying needs, Rollup Boost was built with extensibility in mind. It is designed to support custom block-building features, allowing operators to implement modifications for any variety of block selection or customization rules. + +**Liveness Protection**: To safeguard against liveness risks, Rollup Boost offers a local block production fallback if there is a failure in the external builder. + +**Compatibility**: Rollup Boost allows operators to continue using standard op-node or op-geth software without any custom forks. + +## Is it secure? + +Rollup Boost underwent a security audit on May 11 2025 with [Nethermind](https://www.nethermind.io). See the full report [here](https://github.com/flashbots/rollup-boost/blob/main/docs/NM_0411_0491_Security_Review_World_Rollup_Boost.pdf). + +In addition to the audit, we have an extensive suite of integration and kurtosis tests in our CI to ensure the whole flow works end to end with the OP stack as well as with external builders. + +## Who is this for? + +Rollup Boost is designed for: + +- **Rollup Operators**: Teams running OP Stack or compatible rollups who want to improve efficiency, reduce confirmation times, and have more control over block construction. +- **Rollup Developers**: Engineers building on rollups to unlock new use cases with rollup extensions. +- **Block Builders**: Teams focused on MEV who want to offer specialized block building services for rollups. +- **Researchers**: Those exploring new approaches to MEV and block production strategies. + +## Contributing + diff --git a/book/theme/head.hbs b/book/theme/head.hbs index 15f76b66..e9a1a360 100644 --- a/book/theme/head.hbs +++ b/book/theme/head.hbs @@ -3,4 +3,8 @@ {{!-- TODO: add logo --}} {{!-- --}} -{{!-- --}} \ No newline at end of file +{{!-- --}} + + \ No newline at end of file From 107acf7214c41e622227db25e7dffa27c7ae1582 Mon Sep 17 00:00:00 2001 From: avalonche Date: Tue, 19 Aug 2025 20:22:36 +1000 Subject: [PATCH 2/8] docs --- book/book.toml | 3 + book/src/README.md | 3 - book/src/SUMMARY.md | 33 ++- book/src/architecture/external-building.md | 9 + .../architecture/{overview.md => sidecar.md} | 21 +- book/src/block-building/basics.md | 1 - book/src/cli/flashblocks-rpc.md | 8 + book/src/cli/rollup-boost.md | 19 ++ book/src/cli/websocket-proxy.md | 51 +++++ book/src/configuration/basic.md | 1 - book/src/developers/flashblocks-rpc.md | 205 ++++++++++++++++++ book/src/flashblocks/introduction.md | 1 - book/src/getting-started/installation.md | 1 - book/src/intro.md | 16 +- book/src/modules/flashblocks.md | 48 ++++ book/src/modules/flashtestations.md | 122 +++++++++++ book/src/operators/ha-setup.md | 66 ++++++ book/src/operators/local.md | 46 ++++ book/src/operators/production.md | 200 +++++++++++++++++ crates/websocket-proxy/README.md | 1 + 20 files changed, 828 insertions(+), 27 deletions(-) delete mode 100644 book/src/README.md create mode 100644 book/src/architecture/external-building.md rename book/src/architecture/{overview.md => sidecar.md} (68%) delete mode 100644 book/src/block-building/basics.md create mode 100644 book/src/cli/flashblocks-rpc.md create mode 100644 book/src/cli/rollup-boost.md create mode 100644 book/src/cli/websocket-proxy.md delete mode 100644 book/src/configuration/basic.md create mode 100644 book/src/developers/flashblocks-rpc.md delete mode 100644 book/src/flashblocks/introduction.md delete mode 100644 book/src/getting-started/installation.md create mode 100644 book/src/modules/flashblocks.md create mode 100644 book/src/modules/flashtestations.md create mode 100644 book/src/operators/ha-setup.md create mode 100644 book/src/operators/local.md create mode 100644 book/src/operators/production.md diff --git a/book/book.toml b/book/book.toml index d8d7defd..d5b231a6 100644 --- a/book/book.toml +++ b/book/book.toml @@ -16,5 +16,8 @@ no-section-label = true enable = true level = 1 +[preprocessor.mermaid] +command = "mdbook-mermaid" + [build] build-dir = "book" diff --git a/book/src/README.md b/book/src/README.md deleted file mode 100644 index 3df84959..00000000 --- a/book/src/README.md +++ /dev/null @@ -1,3 +0,0 @@ -# rollup-boost book - -Rollup Boost is a sidecar that enables rollup extensions. \ No newline at end of file diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index 6cc78752..6ca33db0 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -1,8 +1,29 @@ -# Summary +# Table of Contents - [Introduction](./intro.md) -- [Architecture Overview](./architecture/overview.md) -- [Getting Started](./getting-started/installation.md) -- [Configuration](./configuration/basic.md) -- [Block Building](./block-building/basics.md) -- [Flashblocks](./flashblocks/introduction.md) \ No newline at end of file + +# Architecture + +- [External Block Building](./architecture/external-building.md) +- [Rollup Boost Sidecar](./architecture/sidecar.md) + +# Rollup Boost Modules + +- [Flashblocks](./modules/flashblocks.md) +- [Flashtestations](./modules/flashtestations.md) + +# For Rollup Operators + +- [Running Rollup Boost Locally](./operators/local.md) +- [Running Rollup Boost in Production](./operators/production.md) +- [High Availability Setup](./operators/ha-setup.md) + +# For DApp Developers + +- [Flashblocks Data over JSON RPC](./developers/flashblocks-rpc.md) + +# CLI Reference + +- [rollup-boost](./cli/rollup-boost.md) +- [websocket-proxy](./cli/websocket-proxy.md) +- [flashblocks-rpc](./cli/flashblocks-rpc.md) \ No newline at end of file diff --git a/book/src/architecture/external-building.md b/book/src/architecture/external-building.md new file mode 100644 index 00000000..dfb06a4f --- /dev/null +++ b/book/src/architecture/external-building.md @@ -0,0 +1,9 @@ +# External Block Building + +Much like [mev-boost](https://github.com/flashbots/mev-boost) on Ethereum layer 1, rollup-boost is a sidecar run alongside the sequencer in Optimism chains to source blocks from external block builders. Unlike mev-boost, there are no code changes or extra config to support external block building in the consensus node as rollup-boost reuses the existing Engine API to source external blocks. + +![architecture](https://raw.githubusercontent.com/flashbots/rollup-boost/refs/heads/main/assets/rollup-boost-architecture.png) + +Instead of pointing to the local execution client, the rollup operator simply needs to point the consensus node to rollup-boost and configure rollup-boost to both the local execution client and the external block builder. + +To read more about the design, check out the [design doc](https://github.com/ethereum-optimism/design-docs/blob/main/protocol/external-block-production.md) of how rollup-boost integrates into the Optimism stack. diff --git a/book/src/architecture/overview.md b/book/src/architecture/sidecar.md similarity index 68% rename from book/src/architecture/overview.md rename to book/src/architecture/sidecar.md index 2314676b..1102c57d 100644 --- a/book/src/architecture/overview.md +++ b/book/src/architecture/sidecar.md @@ -1,25 +1,30 @@ # Architecture Overview -Rollup Boost modifies the workflow of the engine api to enable block building and flashblocks. +![Rollup Boost OP Conductor](../assets/rollup-boost-op-conductor.png) + +Rollup Boost modifies the workflow of the Engine API to enable block building and flashblocks. It uses the JWT token in the Engine API as authentication for the builder and multiplexes the RPC calls to the builder to source external blocks. ## Core System Workflow -1. `rollup-boost` receives an `engine_FCU` with the attributes to initiate block building: - - It relays the call to proposer `op-geth` as usual and multiplexes the call to builder. +1. `rollup-boost` receives an `engine_FCU` with the attributes to initiate block building: + - It relays the call to proposer `op-geth` as usual and multiplexes the call to builder. - The FCU call returns the proposer payload id and internally maps the builder payload id to proposer payload id in the case the payload ids are not the same. -2. When `rollup-boost` receives an `engine_getPayload`: +2. When `rollup-boost` receives an `engine_getPayload`: - It queries proposer `op-geth` for a fallback block. - In parallel, it queries builder for a block. 3. Upon receiving the builder block: - - `rollup-boost` validates the block with proposer `op-geth` using `engine_newPayload`. + - `rollup-boost` validates the block with proposer `op-geth` using `engine_newPayload`. - This validation ensures the block will be valid for proposer `op-geth`, preventing network stalls due to invalid blocks. - If the external block is valid, it is returned to the proposer `op-node`. Otherwise, `rollup-boost` will return the fallback block. 4. The proposer `op-node` sends a `engine_newPayload` request to `rollup-boost` and another `engine_FCU` without attributes to update chain state. - `rollup-boost` just relays the calls to proposer `op-geth`. - - Note that since we already called `engine_newPayload` on the proposer `op-geth` in the previous step, the block should be cached and add minimal latency. + - Note that since we already called `engine_newPayload` on the proposer `op-geth` in the previous step, the block should be cached and add minimal latency. - The builder `op-node` will receive blocks via p2p gossip and keep the builder node in sync via the engine api. +![OP Stack High Availability](../assets/op-stack-ha.png) + ```mermaid +%%{init: {'theme': 'base', 'themeVariables': { 'background': '#f4f4f4', 'primaryColor': '#2c3e50', 'primaryTextColor': '#ffffff', 'primaryBorderColor': '#34495e', 'lineColor': '#34495e', 'secondaryColor': '#ecf0f1', 'tertiaryColor': '#bdc3c7'}}}%% sequenceDiagram box Proposer participant op-node @@ -65,7 +70,7 @@ By default, `rollup-boost` will proxy all RPC calls from the proposer `op-node` ### Boost Sync -By default, `rollup-boost` will sync the builder with the proposer `op-node`. After the builder is synced, boost sync improves the performance of keeping the builder in sync with the tip of the chainby removing the need to receive chain updates via p2p via the builder `op-node`. This entails additional engine api calls that are multiplexed to the builder from rollup-boost: +`rollup-boost` will use boost sync by default to sync directly with the proposer `op-node` via the Engine API. Boost sync improves the performance of keeping the builder in sync with the tip of the chain by removing the need to receive chain updates via p2p from the builder `op-node` once the builder is synced. This entails additional engine api calls that are multiplexed to the builder from rollup-boost: - `engine_forkchoiceUpdatedV3`: this call will be multiplexed to the builder regardless of whether the call contains payload attributes or not. -- `engine_newPayloadV3`: ensures the builder has the latest block if the local payload was used. \ No newline at end of file +- `engine_newPayloadV3`: ensures the builder has the latest block if the local payload was used. diff --git a/book/src/block-building/basics.md b/book/src/block-building/basics.md deleted file mode 100644 index 17292419..00000000 --- a/book/src/block-building/basics.md +++ /dev/null @@ -1 +0,0 @@ -# Block Building diff --git a/book/src/cli/flashblocks-rpc.md b/book/src/cli/flashblocks-rpc.md new file mode 100644 index 00000000..a6453f42 --- /dev/null +++ b/book/src/cli/flashblocks-rpc.md @@ -0,0 +1,8 @@ +# flashblocks-rpc + + +## Command Line Options + +- `flashblocks.enabled`: Enable flashblocks functionality (default: false) +- `flashblocks.websocket-url`: WebSocket URL for flashblocks stream +- Standard reth/OP Stack options for chain and RPC configuration \ No newline at end of file diff --git a/book/src/cli/rollup-boost.md b/book/src/cli/rollup-boost.md new file mode 100644 index 00000000..fd904de1 --- /dev/null +++ b/book/src/cli/rollup-boost.md @@ -0,0 +1,19 @@ +# rollup-boost + +### Command-line Options + +- `--l2-jwt-token `: JWT token for L2 authentication (required) +- `--l2-jwt-path `: Path to the L2 JWT secret file (required if `--l2-jwt-token` is not provided) +- `--l2-url `: URL of the local L2 execution engine (required) +- `--builder-url `: URL of the builder execution engine (required) +- `--builder-jwt-token `: JWT token for builder authentication (required) +- `--builder-jwt-path `: Path to the builder JWT secret file (required if `--builder-jwt-token` is not provided) +- `--rpc-host `: Host to run the server on (default: 127.0.0.1) +- `--rpc-port `: Port to run the server on (default: 8081) +- `--tracing`: Enable tracing (default: false) +- `--log-level `: Log level (default: info) +- `--log-format `: Log format (default: text) +- `--metrics`: Enable metrics (default: false) +- `--metrics-host `: Host to run the metrics server on (default: 127.0.0.1) +- `--debug-host `: Host to run the server on (default: 127.0.0.1) +- `--debug-server-port `: Port to run the debug server on (default: 5555) \ No newline at end of file diff --git a/book/src/cli/websocket-proxy.md b/book/src/cli/websocket-proxy.md new file mode 100644 index 00000000..5a41a901 --- /dev/null +++ b/book/src/cli/websocket-proxy.md @@ -0,0 +1,51 @@ +# websocket-proxy + +The websocket-proxy is a service + +## Command-line Options + +### Connection Configuration + +- `--listen-addr
`: The address and port to listen on for incoming connections (default: 0.0.0.0:8545) +- `--upstream-ws `: WebSocket URI of the upstream server to connect to (required, can specify multiple with comma separation) + +### Rate Limiting + +- `--instance-connection-limit `: Maximum number of concurrently connected clients per instance (default: 100) +- `--per-ip-connection-limit `: Maximum number of concurrently connected clients per IP (default: 10) +- `--redis-url `: Redis URL for distributed rate limiting (e.g., redis://localhost:6379). If not provided, in-memory rate limiting will be used +- `--redis-key-prefix `: Prefix for Redis keys (default: flashblocks) + +### Message Handling + +- `--message-buffer-size `: Number of messages to buffer for lagging clients (default: 20) +- `--enable-compression`: Enable Brotli compression on messages to downstream clients (default: false) +- `--ip-addr-http-header
`: Header to use to determine the client's origin IP (default: X-Forwarded-For) + +### Authentication + +- `--api-keys `: API keys to allow in format `:,:`. If not provided, the endpoint will be unauthenticated + +### Logging + +- `--log-level `: Log level (default: info) +- `--log-format `: Format for logs, can be json or text (default: text) + +### Metrics + +- `--metrics`: Enable Prometheus metrics (default: true) +- `--metrics-addr
`: Address to run the metrics server on (default: 0.0.0.0:9000) +- `--metrics-global-labels `: Tags to add to every metrics emitted in format `label1=value1,label2=value2` (default: "") +- `--metrics-host-label`: Add the hostname as a label to all Prometheus metrics (default: false) + +### Upstream Connection Management + +- `--subscriber-max-interval-ms `: Maximum backoff allowed for upstream connections in milliseconds (default: 20000) +- `--subscriber-ping-interval-ms `: Interval in milliseconds between ping messages sent to upstream servers to detect unresponsive connections (default: 2000) +- `--subscriber-pong-timeout-ms `: Timeout in milliseconds to wait for pong responses from upstream servers before considering the connection dead (default: 4000) + +### Client Health Checks + +- `--client-ping-enabled`: Enable ping/pong client health checks (default: false) +- `--client-ping-interval-ms `: Interval in milliseconds to send ping messages to clients (default: 15000) +- `--client-pong-timeout-ms `: Timeout in milliseconds to wait for pong response from clients (default: 30000) diff --git a/book/src/configuration/basic.md b/book/src/configuration/basic.md deleted file mode 100644 index a025a48b..00000000 --- a/book/src/configuration/basic.md +++ /dev/null @@ -1 +0,0 @@ -# Configuration diff --git a/book/src/developers/flashblocks-rpc.md b/book/src/developers/flashblocks-rpc.md new file mode 100644 index 00000000..a80d4141 --- /dev/null +++ b/book/src/developers/flashblocks-rpc.md @@ -0,0 +1,205 @@ +# Reading Flashblocks Data over Ethereum JSON RPC + +The Flashblocks RPC implementation provides preconfirmation data through modified Ethereum JSON-RPC endpoints using the `pending` tag. This allows applications to access transaction and state information from Flashblocks before they are finalized on the blockchain. + +## Quick Start + +To run a node capable of serving flashblocks, run the `flashblock-rpc` crate inside the rollup-boost repository. + +Build: + +```bash +cargo build --release +``` + +Run: + +```bash +./target/release/flashblocks-rpc \ + --flashblocks.enabled=true \ + --flashblocks.websocket-url=ws://localhost:8080/flashblocks \ + --chain=optimism \ + --http \ + --http.port=8545 +``` + +## Supported RPC Endpoints + +The following Ethereum JSON-RPC endpoints are modified to support Flashblocks data when queried with the `pending` tag: + +### `eth_getBlockByNumber` + +Retrieves block information including transactions from the pending Flashblock. + +**Request:** +```json +{ + "method": "eth_getBlockByNumber", + "params": ["pending", true], + "id": 1, + "jsonrpc": "2.0" +} +``` + +**Response:** +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "hash": "0x0", + "parentHash": "0x...", + "stateRoot": "0x...", + "transactionsRoot": "0x...", + "receiptsRoot": "0x...", + "number": "0x...", + "gasUsed": "0x...", + "gasLimit": "0x...", + "timestamp": "0x...", + "extraData": "0x...", + "mixHash": "0x...", + "nonce": "0x...", + "transactions": [ + { + "hash": "0x...", + "nonce": "0x...", + "blockHash": "0x0", + "blockNumber": null, + "transactionIndex": "0x0", + "from": "0x...", + "to": "0x...", + "value": "0x...", + "gas": "0x...", + "gasPrice": "0x...", + "input": "0x...", + "v": "0x...", + "r": "0x...", + "s": "0x..." + } + ] + } +} +``` + +**Notes:** +- Returns an empty hash (`0x0`) as the block hash since the block is not yet finalized +- Includes all transactions from received Flashblocks +- Implements an append-only pattern - multiple queries show expanding transaction lists + +### `eth_getTransactionReceipt` + +Retrieves transaction receipt information from the pending Flashblock. + +**Request:** +```json +{ + "method": "eth_getTransactionReceipt", + "params": ["0x..."], + "id": 1, + "jsonrpc": "2.0" +} +``` + +**Response:** +```json +{ + "jsonrpc": "2.0", + "id": 1, + "result": { + "transactionHash": "0x...", + "transactionIndex": "0x0", + "blockHash": "0x0", + "blockNumber": null, + "from": "0x...", + "to": "0x...", + "cumulativeGasUsed": "0x...", + "gasUsed": "0x...", + "contractAddress": null, + "logs": [], + "status": "0x1", + "logsBloom": "0x...", + "effectiveGasPrice": "0x..." + } +} +``` + +**Notes:** +- Returns receipt data for transactions in the pending Flashblock +- `blockHash` is `0x0` and `blockNumber` is `null` since the block is not finalized +- Includes gas usage and execution status information + +### `eth_getBalance` + +Retrieves account balance from the pending state. + +**Request:** +```json +{ + "method": "eth_getBalance", + "params": ["0x...", "pending"], + "id": 1, + "jsonrpc": "2.0" +} +``` + +**Response:** +```json +"0x..." +``` + +**Notes:** +- Returns balance reflecting all changes from preconfirmed transactions +- Uses cached state changes from Flashblocks metadata +- Falls back to standard RPC if no pending data is available + +### `eth_getTransactionCount` + +Retrieves the transaction count (nonce) for an account from the pending state. + +**Request:** +```json +{ + "method": "eth_getTransactionCount", + "params": ["0x...", "pending"], + "id": 1, + "jsonrpc": "2.0" +} +``` + +**Response:** +```json +"0x..." +``` + +**Notes:** +- Returns nonce reflecting all preconfirmed transactions +- Combines latest confirmed nonce with pending transaction count +- Useful for determining the next valid nonce for the next flashblock + +## Data Flow + +The Flashblocks RPC implementation follows this data flow: + +1. **WebSocket Connection**: Establishes connection to rollup-boost Flashblocks endpoint +2. **Payload Reception**: Receives `FlashblocksPayloadV1` messages containing transaction batches +3. **Cache Processing**: Updates in-memory cache with new transaction and state data +4. **RPC Queries**: Responds to client requests using cached pending data +5. **State Management**: Maintains consistency between confirmed and pending states + +## Flashblocks Payload Structure + +Flashblocks payloads contain the following information: + +```rust +pub struct FlashblocksPayloadV1 { + pub version: PayloadVersion, + pub execution_payload: OpExecutionPayloadEnvelope, + pub metadata: Metadata, +} + +pub struct Metadata { + pub receipts: HashMap, + pub new_account_balances: HashMap, + pub block_number: u64, +} +``` \ No newline at end of file diff --git a/book/src/flashblocks/introduction.md b/book/src/flashblocks/introduction.md deleted file mode 100644 index fb00e549..00000000 --- a/book/src/flashblocks/introduction.md +++ /dev/null @@ -1 +0,0 @@ -# Flashblocks diff --git a/book/src/getting-started/installation.md b/book/src/getting-started/installation.md deleted file mode 100644 index bad55622..00000000 --- a/book/src/getting-started/installation.md +++ /dev/null @@ -1 +0,0 @@ -# Getting Started diff --git a/book/src/intro.md b/book/src/intro.md index 02c5d2cc..80a37929 100644 --- a/book/src/intro.md +++ b/book/src/intro.md @@ -1,16 +1,16 @@ # Rollup Boost -Rollup Boost is a lightweight sidecar for rollup to enable rollup extensions. These extensions allows for an efficient, decentralized and verifiable block building platform for rollups. +Rollup Boost is a lightweight sidecar for rollups that enables rollup extensions. These extensions allow for an efficient, decentralized, and verifiable block building platform for rollups. ## What is Rollup Boost? -[Rollup Boost](https://github.com/flashbots/rollup-boost/) uses the [Engine API](https://specs.optimism.io/protocol/exec-engine.html#engine-api) in the Optimism stack to enable its rollup extensions. This requires no modification to the OP stack software and enable rollup operators to connect to an external builder. +[Rollup Boost](https://github.com/flashbots/rollup-boost/) uses the [Engine API](https://specs.optimism.io/protocol/exec-engine.html#engine-api) in the Optimism stack to enable its rollup extensions. This requires no modification to the OP stack software and enables rollup operators to connect to an external builder. It is designed and developed by [Flashbots](https://flashbots.net/) under a MIT license. We invite developers, rollup operators, and researchers to join in developing this open-source software to achieve efficiency and decentralization in the rollup ecosystem. ## What are the design goals of Rollup Boost? -**Simplicity**: Rollup Boost was designed with minimal complexity and maintaining a lightweight setup avoids additional latency. By focusing on simplicity, Rollup Boost integrates smoothly into the OP stack without disrupting existing op-node and execution engine communication. +**Simplicity**: Rollup Boost was designed with minimal complexity, and maintaining a lightweight setup avoids additional latency. By focusing on simplicity, Rollup Boost integrates smoothly into the OP stack without disrupting existing op-node and execution engine communication. **Modularity**: Recognizing that rollups have varying needs, Rollup Boost was built with extensibility in mind. It is designed to support custom block-building features, allowing operators to implement modifications for any variety of block selection or customization rules. @@ -18,11 +18,13 @@ It is designed and developed by [Flashbots](https://flashbots.net/) under a MIT **Compatibility**: Rollup Boost allows operators to continue using standard op-node or op-geth software without any custom forks. +See this [doc](https://github.com/flashbots/rollup-boost/blob/main/docs/design-philosophy-testing-strategy.md) for the design philosophy and testing strategy for Rollup Boost. + ## Is it secure? -Rollup Boost underwent a security audit on May 11 2025 with [Nethermind](https://www.nethermind.io). See the full report [here](https://github.com/flashbots/rollup-boost/blob/main/docs/NM_0411_0491_Security_Review_World_Rollup_Boost.pdf). +Rollup Boost underwent a security audit on May 11, 2025, with [Nethermind](https://www.nethermind.io). See the full report [here](https://github.com/flashbots/rollup-boost/blob/main/docs/NM_0411_0491_Security_Review_World_Rollup_Boost.pdf). -In addition to the audit, we have an extensive suite of integration and kurtosis tests in our CI to ensure the whole flow works end to end with the OP stack as well as with external builders. +In addition to the audit, we have an extensive suite of integration and kurtosis tests in our CI to ensure the whole flow works end-to-end with the OP stack as well as with external builders. ## Who is this for? @@ -33,5 +35,7 @@ Rollup Boost is designed for: - **Block Builders**: Teams focused on MEV who want to offer specialized block building services for rollups. - **Researchers**: Those exploring new approaches to MEV and block production strategies. -## Contributing +## Getting Help +- GitHub Issues: Open an [issue](https://github.com/flashbots/rollup-boost/issues/new) for bugs or feature requests +- Forum: Join the [forum](https://collective.flashbots.net/c/rollup-boost) for development updates and research topics \ No newline at end of file diff --git a/book/src/modules/flashblocks.md b/book/src/modules/flashblocks.md new file mode 100644 index 00000000..29515e95 --- /dev/null +++ b/book/src/modules/flashblocks.md @@ -0,0 +1,48 @@ +# Flashblocks + +Flashblocks is a rollup-boost module that enables fast confirmation times by breaking down block construction into smaller, incremental sections. This feature allows for pre-confirmations and improved user experience through faster block finalization. + +## Architecture + +The Flashblocks setup consists of three main components: + +- **rollup-boost**: The main service with Flashblocks enabled +- **op-rbuilder**: A builder with Flashblocks support +- **op-reth**: A fallback builder (standard EL node) + +It utilizes websockets to stream flashblocks from the builder to rollup-boost to minimize the latency between the flashblocks and the sequencer. + +### Flashblocks Workflow + +```mermaid +flowchart LR + subgraph Sequencer + ON[OP Node] + RB[Rollup Boost] + FEL[Fallback EL] + BB[Block Builder] + end + + subgraph Network + WSP[WebSocket Proxy] + end + + subgraph Clients + RPC[RPC Providers] + Users[End Users] + end + + ON --> RB + RB --> FEL + RB <--> BB + RB --> WSP + WSP --> RPC + RPC --> Users +``` + +1. **Websocket Communication**: Flashblocks utilizes websockets to stream flashblocks from the builder to rollup-boost once its constructed to minimize the latency between the flashblocks and the sequencer. +2. **Websocket Proxy**: rollup-boost caches these flashblocks and streams them to a websocket proxy. The proxy then fans out the flashblocks to downstream rpc providers. +3. **RPC Overlay**: Once RPC providers receive these flashblocks from the proxy, clients need to run a modified node that supports serving RPC requests with the flashblocks preconfirmation state. +4. **Full Block**: At the end of the slot, the proposer requests a full block from rollup-boost. If rollup-boost does not have the flashblocks cached due to a lost connection, it will fallback to the getPayload call to both the local execution client and the builder. + +See the [specs](https://github.com/flashbots/rollup-boost/blob/main/specs/flashblocks.md) for the full design details for flashblocks. \ No newline at end of file diff --git a/book/src/modules/flashtestations.md b/book/src/modules/flashtestations.md new file mode 100644 index 00000000..83c52197 --- /dev/null +++ b/book/src/modules/flashtestations.md @@ -0,0 +1,122 @@ +# Flashtestations + +Flashtestations is a rollup-boost module that provides onchain TEE (Trusted Execution Environment) attestations and block proofs to verifiably prove that blocks were built inside a TEE. This provides user guarantees such as priority ordering. + +## Architecture + +``` +┌─────────────────────────┐ ┌─────────────────────┐ +│ TDX VM │ │ Onchain Verifier │ +│ │ Attestation │ │ +│ ┌─────────────────┐ │ Quote │ ┌─────────────────┐ │ +│ │ TEE Workload │ │ ───────────────► │ │ DCAP Attestation│ │ +│ │ │ │ │ │ Verifier │ │ +│ │ (measurements) │ │ │ │ │ │ +│ └─────────────────┘ │ │ └────────┬────────┘ │ +│ │ │ │ │ +└─────────────────────────┘ │ ▼ │ + │ ┌─────────────────┐ │ +┌─────────────────────────┐ │ │ Intel │ │ +│ Consumer Contract │ │ │ Endorsements │ │ +│ │ │ │ │ │ +│ ┌─────────────────┐ │ │ └────────┬────────┘ │ +│ │ Operation │ │ │ │ │ +│ │ Authorization │ │ │ ▼ │ +│ └─────────────────┘ │ │ ┌─────────────────┐ │ +│ │ │ │ │ Registration │ │ +└─────────┼───────────────┘ │ │ Logic │ │ + │ │ └────────┬────────┘ │ + │ └──────────┼──────────┘ + │ │ +┌─────────▼──────────────┐ ▼ +│ Policy │ ┌───────────────────────────┐ +│ │ isValid │ Flashtestation Registry │ +│ ┌─────────────────────┐│ Query │ │ +│ │ allowedWorkloadIds[]││ ◄───────────────►│ {teeAddress: registration}│ +│ │ {registration: ││ │ map │ +│ │ workloadId} map ││ │ │ +│ └─────────────────────┘│ └───────────────────────────┘ +└────────────────────────┘ +``` + +### Core Components + +1. **Onchain Verifier**: Validates TDX attestation quotes against current Intel endorsements. Provides cryptographic proof that a TEE-controlled address is generated within genuine TDX hardware +2. **Flashtestation Registry**: Tracks TEE-controlled addresses with valid attestations +3. **Policy Registry**: Defines which workloads are acceptable for specific operations +4. **Transparency Log**: Records all attestation events and endorsement changes + +## Flashtestations Workflow + +Flashtestations involve two main workflows: + +- Registering the block builder's TEE attestation +- Block builder TEE proof + +### TEE Attestation Registration + +1. **TEE Environment Setup**: The builder runs in a TDX environment with specific measurement registers. These are measurements of a reproducible build for a specific builder code commit and config. +2. **TEE Key Generation**: The builder generates a key pair on startup that never leaves the TEE environment +3. **Quote Generation**: The TEE generates an attestation quote containing: + - Measurement registers + - Report data with TEE-controlled address and any extra registration data +3. **Onchain Verification**: The quote is submitted onchain by the builder to the registry contract. The contract verifies that the quote is valid and the TEE address from the report data + +### Policy Layer + +The policy layer provides authorization for TEE services. This allows operators to authorize that only builders running a specific commit and config can submit TEE block proofs. + +Upon registration, a workloadId is derived from the measurements in the quote and operators can manage which workload ids are considered valid for a specific rollup. + +The Policy Registry can store metadata linking workload IDs to source code: + +```solidity +struct WorkloadMetadata { + string commitHash; // Git commit hash of source code + string[] sourceLocators; // URIs pointing to source code (https://, git://, ipfs://) +} +``` + +### Block Builder TEE Proofs + +If the builder has registered successfully with an authorized workload id, builders can append a verification transaction to each block. + +The block proof will be signed by the generated TEE address. Since the TEE address never leaves the TEE environment, we can ensure that block proofs signed by that key mean that the block was built inside a TEE. + +The builder will submit a transaction containing a block content hash, which is computed as: + +```solidity +function ComputeBlockContentHash(block, transactions) { + transactionHashes = [] + for each tx in transactions: + txHash = keccak256(rlp_encode(tx)) + transactionHashes.append(txHash) + + return keccak256(abi.encode( + block.parentHash, + block.number, + block.timestamp, + transactionHashes + )) +} +``` + +## Security Considerations + +### Critical Security Assumptions + +- **Private Key Management**: TEE private keys must never leave the TEE boundaries +- **Attestation Integrity**: TEEs must not allow external control over `ReportData` field +- **Reproducible Builds**: Workloads must be built using reproducible processes + +### Security Properties + +- **Block Authenticity**: Cryptographic proof that blocks were produced by authorized TEEs with specific guarantees with the workload id +- **Auditability**: All proofs are recorded onchain for transparency + +## References + +- [Intel TDX Specifications](https://www.intel.com/content/www/us/en/developer/tools/trust-domain-extensions/documentation.html) +- [Intel DCAP Quoting Library API](https://download.01.org/intel-sgx/latest/dcap-latest/linux/docs/Intel_TDX_DCAP_Quoting_Library_API.pdf) +- [Automata DCAP Attestation Contract](https://github.com/automata-network/automata-dcap-attestation) +- [Automata On-chain PCCS](https://github.com/automata-network/automata-on-chain-pccs) diff --git a/book/src/operators/ha-setup.md b/book/src/operators/ha-setup.md new file mode 100644 index 00000000..8194bc26 --- /dev/null +++ b/book/src/operators/ha-setup.md @@ -0,0 +1,66 @@ +# High Availability Setup + +The current OP Stack sequencer HA design relies on `op-conductor` to manage a cluster of sequencers. In the rollup-boost HA setup, each sequencer connects to its own builder instance. In the event of sequencer failover, `op-conductor` elects a new leader, promoting a different `op-node` along with its associated `rollup-boost` and builder instance. + +![HA Setup](https://raw.githubusercontent.com/flashbots/rollup-boost/refs/heads/main/assets/1-1-builder-rb.png) + +If the builder produces undesirable but valid blocks, operators must either manually disable external block production via the `rollup-boost` debug API, disable the block builder directly (causing health checks to fail), or manually select a new sequencer leader. + +See the [design doc](https://github.com/flashbots/rollup-boost/blob/main/docs/rollup-boost-ha.md) for more detail on the design principles for the HA setup with rollup-boost. + +## Health Checks + +In high availability deployments, `op-conductor` must assess the full health of the block production path. Rollup Boost will expose a composite `/healthz` endpoint to report on both builder synchronization and payload production status. These checks allow `op-conductor` to detect degraded block building conditions and make informed leadership decisions. + +Rollup Boost will continuously monitors two independent conditions to inform the health of the builder and the default execution client: + +- **Builder Synchronization**: + A background task periodically queries the builder’s latest unsafe block via `engine_getBlockByNumber`. The task compares the timestamp of the returned block to the local system time. If the difference exceeds a configured maximum unsafe interval (`max_unsafe_interval`), the builder is considered out of sync. Failure to fetch a block from the builder or detection of an outdated block timestamp results in the health status being downgraded to Partial. If the builder is responsive and the block timestamp is within the acceptable interval, the builder is considered synchronized and healthy. Alternatively instead of periodic polling, builder synchronization can be inferred if the builder returns a `VALID` response to a `newPayload` call forwarded from Rollup Boost. + +- **Payload Production**: + During each `get_payload` request, Rollup Boost will verify payload availability from both the builder and the execution client. If the builder fails to deliver a payload, Rollup Boost will report partial health. If the execution client fails to deliver a payload, Rollup Boost will report unhealthy. + +`op-conductor` should also be configurable in how it interprets health status for failover decisions. This allows chain operators to define thresholds based on their risk tolerance and operational goals. For example, operators may choose to maintain leadership with a sequencer reporting `206 Partial Content` to avoid unnecessary fail overs or they may configure `op-conductor` to immediately fail over when any degradation is detected. This flexibility allows the chain operator to configure a failover policy that aligns with network performance expectations and builder reliability. + +
+ +| Condition | Health Status | +|:----------|:--------------| +| Builder is synced and both execution client and builder return payloads | `200 OK` (Healthy) | +| Builder is out of sync| `206 Partial Content` (Partially Healthy) | +| Builder fails to return payload on `get_payload` request | `206 Partial Content` (Partially Healthy) | +| Execution client fails to return payload on `get_payload` request | `503 Service Unavailable` (Unhealthy) | + +`op-conductor` should query the `/healthz` endpoint exposed by Rollup Boost in addition to the existing execution client health checks. Health should be interpreted as follows: + +- `200 OK` (Healthy): The node is fully healthy and eligible for leadership. +- `206 Partial Content` (Partially Healthy): The node is degraded but may be considered for leadership if configured by operator +- `503 Service Unavailable` (Unhealthy): The node is unhealthy and must be excluded from leadership. + +During normal operation and leadership transfers, `op-conductor` should prioritize sequencer candidates in the following order: + +1. Prefer nodes reporting `200 OK`. +2. Nodes that return `503 Service Unavailable` are treated as unhealthy and must not be eligible for sequencer leadership. `op-conductor` should offer a configuration option to treat nodes returning `206 Partial Content` as either healthy or unhealthy. + +Rollup Boost instances that are not actively sequencing rely on the builder sync check to report health, as they are not producing blocks. This behavior mirrors the existing `op-conductor` health checks for inactive sequencers and ensures readiness during failover without compromising network liveness guarantees. Note that `op-conductor` will still evaluate existing sequencer health checks to determine overall sequencer health. + +Note that in the case where the builder is unhealthy, `rollup-boost` should bypass forwarding block production requests to the builder entirely and immediately use the default execution client for payload construction. This avoids introducing unnecessary latency to wait for the builder response to timeout. + +When builder health is restored, normal request forwarding and payload selection behavior will resume. + +
+ +## Failure Scenarios + +Below is a high level summary of how each failure scenario is handled. All existing failure modes assumed by upstream `op-conductor` are maintained: + +| Failure Scenario | Category | Scenario and Solution | +| --- | --- | --- | +| Leader Sequencer Execution Client Fails | Sequencer Failure | `op-conductor` will detect an unhealthy status from both `rollup-boost` and pre-existing sequencer health checks, causing Conductor to elect a new leader. Once the default execution client has recovered, `rollup-boost` will update it's health status to `200` and the sequencer will continue operating normally as a follower. | +| Follower Sequencer Execution Client Fails | Sequencer Failure | Both `rollup-boost` and pre-existing sequencer health checks will report "unhealthy". Once the default exectuion client has recovered, `rollup-boost` will update it's health status to `200` and the sequencer will continue operating normally as a follower. In the event of leadership transfer, this sequencer instance will not be considered for leadership.| +| Leader `rollup-boost` Fails | Rollup Boost Failure | Leader sequencer `rollup-boost` becomes unhealthy, causing `op-conductor`s sequencer health checks to fail and attempt to elect a new leader. This failure mode is the same as a typical leader sequencer failure. Once the sequencer recovers, it will continue to participate in the cluster as a follower| +| Follower `rollup-boost` Fails | Rollup Boost Failure | Follower sequencer `rollup-boost` becomes unhealthy. The leader sequencer is unaffected. Once the sequencer recovers, it will continue to participate in the cluster as a follower.| +| Leader Builder Stops Producing Blocks | Builder Failure | The builder associated with the sequencer leader stops producing new payloads. `rollup-boost` will detect the builder failure via background health checks and downgrade its health status to partial. This will result in `rollup-boost` ignoring the builder and selecting the default execution client's payload for block production. If `op-conductor` is configured to failover upon partial `rollup-boost` health, a new leader will attempt to be elected. Once the builder recovers and resumes payload production, `rollup-boost` will update its health to `200` and resume with normal operation. | +| Leader Builder Falls Out of Sync | Builder Failure | The builder associated with the sequencer leader falls out of sync with the chain head. `rollup-boost` will detect the unsynced state via the background health checks and downgrade its health status to partial. This will result in `rollup-boost` ignoring builder payloads and selecting the default execution client payload for block until the builder is resynced. If `op-conductor` is configured to failover upon partial `rollup-boost` health, a new leader will attempt to be elected. Once the builder recovers, `rollup-boost` will update its health to `200` and resume with normal operation. | +| Follower Builder Falls Out of Sync | Builder Failure | The builder associated with a follower sequencer falls out of sync with the chain head. Block production is unaffected while the node remains a follower. In the event a leader election occurs and `op-conductor` is configured to treat partial health as "unhealthy", this instance will not be eligible for leadership. Once the builder recovers, `rollup-boost` will report `200 OK` and resume normal operation.| +| Leader Builder Producing Bad Blocks| Builder Failure| In this scenario, the builder is "healthy" but producing bad blocks (eg. empty blocks). If the builder block passes validation via a `new_payload` call to the default execution client, it will be proposed to the network. Manual intervention is needed to either switch to a different sequencer or shutoff the builder. Further mitigation can be introduced via block selection policy allowing `rollup-boost` to select the "healthiest" block. Currently, it is unclear what block selection policy would provide the strongest guarantees.| diff --git a/book/src/operators/local.md b/book/src/operators/local.md new file mode 100644 index 00000000..98ac74ea --- /dev/null +++ b/book/src/operators/local.md @@ -0,0 +1,46 @@ +# Running Rollup Boost Locally + +To run a local development network, you can use either Kurtosis or builder-playground to spin up the op-stack with rollup boost. This would include spinning up: + +- sequencer `op-node` and `op-geth` +- builder `op-node` and `op-rbuilder` +- rollup boost `rollup-boost` +- ethereum l1 devnet with l2 contracts deployed +- `op-proposer` and `op-batcher` + +## Kurtosis + +Kurtosis is a tool to manage containerized services. To run rollup-boost in an op-stack devnet first make sure you have [just](https://github.com/casey/just), and [kurtosis-cli](https://docs.kurtosis.com/install/) installed. + +Then run the following command to start the devnet: + +```sh +just devnet-up +``` + +To stop the devnet run: + +```sh +just devnet-down +``` + +To run a stress test against the devnet with [contender](https://github.com/flashbots/contender) first make sure you have docker installed. + +Then run the following command: + +```sh +just stress-test +``` + +See the [optimism package](https://github.com/ethpandaops/optimism-package/blob/main/README.md#configuration) for additional configuration options. + +## Builder Playground + +Builder playground is a tool to deploy an end-to-end environment locally. It can be used to test both L1 and OP Stack block builders. + +To run a + +In this setup, there is a prefunded test account to send test transactions at: + +- address: 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 +- private key: ac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 diff --git a/book/src/operators/production.md b/book/src/operators/production.md new file mode 100644 index 00000000..0c152864 --- /dev/null +++ b/book/src/operators/production.md @@ -0,0 +1,200 @@ +# Running Rollup Boost in Production + +## Regular Sequencer Setup + +To run rollup boost with a regular sequencer setup, change the `--l2` flag in the proposer `op-node` to point to the rollup boost rpc endpoint. + +To configure rollup-boost, set the l2 url to the url of the proposer auth rpc endpoint and the builder url to the builder auth rpc endpoint. Separate JWT tokens will be needed for the two endpoints. + +You can also set the options using environment variables. See .env.example to use the default values. + +```bash +cargo run --bin rollup-boost -- --l2-jwt-token your_jwt_token --l2-url http://localhost:8545 --builder-jwt-token your_jwt_token --builder-url http://localhost:8546 +``` + +To set up a builder, you can use [`op-rbuilder`](https://github.com/flashbots/op-rbuilder) with an op-node instance and have rollup-boost point to the builder auth rpc endpoint. + +## Flashblocks + +To launch rollup-boost with Flashblocks enabled: + +```bash +cargo run --bin rollup-boost -- \ + --l2-url http://localhost:5555 \ + --builder-url http://localhost:4445 \ + --l2-jwt-token 688f5d737bad920bdfb2fc2f488d6b6209eebda1dae949a8de91398d932c517a \ + --builder-jwt-token 688f5d737bad920bdfb2fc2f488d6b6209eebda1dae949a8de91398d932c517a \ + --rpc-port 4444 \ + --flashblocks \ + --log-level info +``` + +This command uses the default Flashblocks configuration. For custom configurations, see the [Flashblocks Configuration](#flashblocks-configuration) section below. + +#### Default Port Configuration + +- `4444`: rollup-boost RPC port +- `4445`: op-rbuilder auth RPC port (matches rollup-boost builder URL) +- `5555`: op-reth auth RPC port (matches rollup-boost L2 URL) +- `3030`: op-rbuilder P2P port +- `3131`: op-reth P2P port + +### Flashblocks Configuration + +rollup-boost provides several configuration options for Flashblocks functionality: + +#### Basic Flashblocks Flag + +- `--flashblocks`: Enable Flashblocks client (required) + - Environment variable: `FLASHBLOCKS` + +#### WebSocket Connection Settings + +- `--flashblocks-builder-url `: Flashblocks Builder WebSocket URL + + - Environment variable: `FLASHBLOCKS_BUILDER_URL` + - Default: `ws://127.0.0.1:1111` + +- `--flashblocks-host `: Flashblocks WebSocket host for outbound connections + + - Environment variable: `FLASHBLOCKS_HOST` + - Default: `127.0.0.1` + +- `--flashblocks-port `: Flashblocks WebSocket port for outbound connections + - Environment variable: `FLASHBLOCKS_PORT` + - Default: `1112` + +#### Connection Management + +- `--flashblock-builder-ws-reconnect-ms `: Timeout duration if builder disconnects + - Environment variable: `FLASHBLOCK_BUILDER_WS_RECONNECT_MS` + - No default value specified + +## Execution mode + +`ExecutionMode` is a configuration setting that controls how `rollup-boost` interacts with the external builder during block production. Execution mode can be set either at startup via CLI flags or dynamically modified at runtime through the [Debug API](#debug-api). +Operators can use `ExecutionMode` to selectively forward or bypass builder interactions, enabling dry runs during deployments or fully disabling external block production during emergencies. + +The available execution modes are: + +- `Enabled` + - `rollup-boost` forwards all Engine API requests to both the builder and default execution client. + - Optimistically selects the builder’s payload for validation and block publication. + - Falls back to the local execution client *only* if the builder fails to produce a payload or the payload is invalid. + - Default setting for normal external block production. + +- `DryRun` + - `rollup-boost` forwards all Engine API requests to both the builder and default execution client. + - Builder payloads are validated with the local execution client but the default execution client block will always be returned to `op-node` to propagate to the network. + - Useful during deployments, dry runs, or to validate builder behavior without publishing builder blocks to the network. + +- `Disabled` + - `rollup-boost` does not forward any Engine API requests to the builder. + - Block construction is handled exclusively by the default execution client. + - Useful as an emergency shutoff switch in the case of critical failures/emergencies. + +```rust +pub enum ExecutionMode { + /// Forward Engine API requests to the builder, validate builder payloads and propagate to the network + Enabled, + /// Forward Engine API requests to the builder, validate builder payloads but + /// fallback to default execution payload + DryRun, + // Do not forward Engine API requests to the builder + Disabled, +} +``` + +
+ +## Debug API + +`rollup-boost` exposes a Debug API that allows operators to inspect and modify the current execution mode at runtime without restarting the service. This provides flexibility to dynamically enable, disable, or dry-run external block production based on builder behavior or network conditions. The Debug API is served over HTTP using JSON RPC and consists of the following endpoints: + +### `debug_setExecutionMode` + +Sets the current execution mode for `rollup-boost`. + +**Request**: + +``` +{ + "method": "debug_setExecutionMode", + "params": [ "enabled" | "dry_run" | "disabled" ], + "id": 1, + "jsonrpc": "2.0" +} +``` + +**Response**: + +``` +{ + "result": null, + "id": 1, + "jsonrpc": "2.0" +} +``` + +### `debug_getExecutionMode` + +Retrieves the current execution mode. + +**Request**: + +``` +{ + "method": "debug_getExecutionMode", + "params": [], + "id": 1, + "jsonrpc": "2.0" +} +``` + +**Response:** + +``` +{ + "result": "enabled" | "dry_run" | "disabled", + "id": 1, + "jsonrpc": "2.0" +} +``` + +## Observability + +### Metrics + +To enable metrics, you can set the `--metrics` flag. This will start a metrics server which will run on port 9090 by default. To see the list of metrics, you can checkout [metrics.rs](../src/metrics.rs) and ping the metrics endpoint: + +``` +curl http://localhost:9090/metrics +``` + +All spans create duration histogram metrics with the name "{span_name}\_duration". Currently, this list includes: + +- fork_choice_updated_v3_duration +- get_payload_v3_duration +- new_payload_v3_duration + +Additionally, execution engines such as op-rbuilder has rpc metrics exposed to check if `engine_getPayloadV3` requests have been received. To check if the builder blocks are landing on-chain, the builder can be configured to include a builder transaction in the block, which is captured as part of the builder metrics. To see more details about observability in the op-builder, you can check op-rbuilder's [README](https://github.com/flashbots/rollup-boost?tab=readme-ov-file#rollup-boost). + +### Tracing + +Tracing is enabled by setting the `--tracing` flag. This will start exporting traces to the otlp endpoint specified in the `--otlp-endpoint` flag. This endpoint is set to `http://localhost:4317` by default. + +Traces use the payload id to track the block building lifecycle. A distributed tracing system such as [Jaeger](https://www.jaegertracing.io/) can be used to visualize when the proposer triggers block building via `engine_forkchoiceUpdatedV3` and retrieve the block with `engine_getPayloadV3`. + +## Troubleshooting Builder Responses + +### Invalid Builder Payloads + +If there are logs around the builder payload being invalid, it is likely there is an issue with the builder and you will need to contact the builder operator to resolve it. In this case rollup-boost will use the local payload and chain liveness will not be affected. You can also manually set rollup-boost to dry run mode using the debug api to stop payload requests to the builder, silencing the error logs. + +It is also possible that either the builder or the proposer execution engine are not running on compatible hard fork versions. Please check that the clients are running on compatible versions of the op-stack. + +### Builder Syncing + +Alternatively, the builder may be syncing with the chain and not have a block to respond with. You can see in the logs the builder is syncing by checking whether the payload_status of builder calls is `SYNCING`. + +This is expected if the builder is still syncing with the chain. Chain liveness will not be affected as rollup-boost will use the local payload. Contact the builder operator if the sync status persists as the builder op-node may be offline or not peered correctly with the network. \ No newline at end of file diff --git a/crates/websocket-proxy/README.md b/crates/websocket-proxy/README.md index 2443fafa..65c7f649 100644 --- a/crates/websocket-proxy/README.md +++ b/crates/websocket-proxy/README.md @@ -27,6 +27,7 @@ cargo test --all-features ``` ### Deployment + Builds of the websocket proxy [are provided](https://github.com/base/flashblocks-websocket-proxy/pkgs/container/flashblocks-websocket-proxy). The only configuration required is the rollup-boost URL to proxy. You can set this via an env var `UPSTREAM_WS` or a flag `--upstream-ws`. From 393b3c7353251cbbbc6c9cc90e1373c85c07d8eb Mon Sep 17 00:00:00 2001 From: avalonche Date: Wed, 20 Aug 2025 06:19:08 +1000 Subject: [PATCH 3/8] fix ci --- .github/workflows/book-tests.yml | 37 +++++++++++++++++++------------- 1 file changed, 22 insertions(+), 15 deletions(-) diff --git a/.github/workflows/book-tests.yml b/.github/workflows/book-tests.yml index 77c40eb7..822fd5c7 100644 --- a/.github/workflows/book-tests.yml +++ b/.github/workflows/book-tests.yml @@ -18,16 +18,19 @@ jobs: steps: - uses: actions/checkout@v4 - - name: Install mdbook + - name: Set up Rust + uses: dtolnay/rust-toolchain@stable + with: + toolchain: stable + override: true + components: rustfmt + + - name: Install Dependencies run: | - mkdir mdbook - curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.14/mdbook-v0.4.14-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook - echo $(pwd)/mdbook >> $GITHUB_PATH - - name: Install mdbook-template - run: | - mkdir mdbook-template - curl -sSL https://github.com/sgoudham/mdbook-template/releases/latest/download/mdbook-template-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook-template - echo $(pwd)/mdbook-template >> $GITHUB_PATH + cargo install mdbook + cargo install mdbook-mermaid + cargo install mdbook-template + - name: Run tests working-directory: ./book run: mdbook test @@ -40,13 +43,17 @@ jobs: steps: - uses: actions/checkout@v4 - - name: Install mdbook-linkcheck + - name: Set up Rust + uses: dtolnay/rust-toolchain@stable + with: + toolchain: stable + override: true + components: rustfmt + + - name: Install Dependencies run: | - mkdir mdbook-linkcheck - curl -sSL -o mdbook-linkcheck.zip https://github.com/Michael-F-Bryan/mdbook-linkcheck/releases/latest/download/mdbook-linkcheck.x86_64-unknown-linux-gnu.zip - unzip mdbook-linkcheck.zip -d ./mdbook-linkcheck - chmod +x $(pwd)/mdbook-linkcheck/mdbook-linkcheck - echo $(pwd)/mdbook-linkcheck >> $GITHUB_PATH + cargo install mdbook-linkcheck + - name: Run linkcheck working-directory: ./book run: mdbook-linkcheck --standalone From 5c3f79161b1446835593c328a1ec2283662f96b3 Mon Sep 17 00:00:00 2001 From: avalonche Date: Wed, 20 Aug 2025 06:23:14 +1000 Subject: [PATCH 4/8] fix links --- book/src/architecture/sidecar.md | 4 ---- book/src/operators/production.md | 2 +- 2 files changed, 1 insertion(+), 5 deletions(-) diff --git a/book/src/architecture/sidecar.md b/book/src/architecture/sidecar.md index 1102c57d..704b4b95 100644 --- a/book/src/architecture/sidecar.md +++ b/book/src/architecture/sidecar.md @@ -1,7 +1,5 @@ # Architecture Overview -![Rollup Boost OP Conductor](../assets/rollup-boost-op-conductor.png) - Rollup Boost modifies the workflow of the Engine API to enable block building and flashblocks. It uses the JWT token in the Engine API as authentication for the builder and multiplexes the RPC calls to the builder to source external blocks. ## Core System Workflow @@ -21,8 +19,6 @@ Rollup Boost modifies the workflow of the Engine API to enable block building an - Note that since we already called `engine_newPayload` on the proposer `op-geth` in the previous step, the block should be cached and add minimal latency. - The builder `op-node` will receive blocks via p2p gossip and keep the builder node in sync via the engine api. -![OP Stack High Availability](../assets/op-stack-ha.png) - ```mermaid %%{init: {'theme': 'base', 'themeVariables': { 'background': '#f4f4f4', 'primaryColor': '#2c3e50', 'primaryTextColor': '#ffffff', 'primaryBorderColor': '#34495e', 'lineColor': '#34495e', 'secondaryColor': '#ecf0f1', 'tertiaryColor': '#bdc3c7'}}}%% sequenceDiagram diff --git a/book/src/operators/production.md b/book/src/operators/production.md index 0c152864..8d826762 100644 --- a/book/src/operators/production.md +++ b/book/src/operators/production.md @@ -165,7 +165,7 @@ Retrieves the current execution mode. ### Metrics -To enable metrics, you can set the `--metrics` flag. This will start a metrics server which will run on port 9090 by default. To see the list of metrics, you can checkout [metrics.rs](../src/metrics.rs) and ping the metrics endpoint: +To enable metrics, you can set the `--metrics` flag. This will start a metrics server which will run on port 9090 by default. To see the list of metrics, you can checkout metrics.rs and ping the metrics endpoint: ``` curl http://localhost:9090/metrics From 69c193ba8bac640d76da2346a83fa62ec3ec73a0 Mon Sep 17 00:00:00 2001 From: avalonche Date: Wed, 20 Aug 2025 06:37:57 +1000 Subject: [PATCH 5/8] fix mdbook tests --- .vercel/build.sh | 33 ++++--------- book/src/developers/flashblocks-rpc.md | 2 +- book/src/modules/flashtestations.md | 66 +++++++++++++------------- book/src/operators/production.md | 10 ++-- 4 files changed, 48 insertions(+), 63 deletions(-) diff --git a/.vercel/build.sh b/.vercel/build.sh index 5e899e2a..fece1a3c 100644 --- a/.vercel/build.sh +++ b/.vercel/build.sh @@ -5,15 +5,8 @@ mkdir -p $HOME/bin export PATH=$HOME/bin:$PATH REPO_ROOT=$(pwd) -echo "Installing mdbook..." -curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.14/mdbook-v0.4.14-x86_64-unknown-linux-gnu.tar.gz | tar -xz -chmod +x ./mdbook -cp ./mdbook $HOME/bin/ - -echo "Installing mdbook-template..." -curl -sSL https://github.com/sgoudham/mdbook-template/releases/latest/download/mdbook-template-x86_64-unknown-linux-gnu.tar.gz | tar -xz -chmod +x ./mdbook-template -cp ./mdbook-template $HOME/bin/ +echo "Installing system dependencies..." +apt-get update && apt-get install -y clang libclang-dev echo "Installing Rust..." curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | RUSTUP_HOME=/tmp/rustup HOME=/tmp sh -s -- -y @@ -24,6 +17,11 @@ export CARGO_HOME=/tmp/.cargo rustup toolchain install nightly rustup default nightly +echo "Installing mdbook..." +cargo install mdbook +cargo install mdbook-template +cargo install mdbook-mermaid + echo "Verifying installations..." which mdbook which mdbook-template @@ -33,21 +31,8 @@ echo "Building the book..." cd "${REPO_ROOT}/book" mdbook build -echo "Building Rust documentation..." -cd "${REPO_ROOT}" -export RUSTDOCFLAGS="--cfg docsrs --show-type-layout --generate-link-to-definition --enable-index-page -Zunstable-options" -cargo doc --all-features --no-deps || { - echo "Cargo doc failed, but continuing with mdbook only" -} - -# Try to copy the API docs if they were generated -if [ -d "${REPO_ROOT}/target/doc" ]; then - echo "Copying API documentation..." - mkdir -p "${REPO_ROOT}/book/book/api" - cp -r "${REPO_ROOT}/target/doc"/* "${REPO_ROOT}/book/book/api/" -else - echo "API documentation not generated, continuing with mdbook only" -fi +echo "Skipping Rust documentation build to avoid libclang dependency..." +echo "Building mdbook documentation only..." # Create a final output directory for Vercel mkdir -p "${REPO_ROOT}/vercel-output" diff --git a/book/src/developers/flashblocks-rpc.md b/book/src/developers/flashblocks-rpc.md index a80d4141..a3ed817a 100644 --- a/book/src/developers/flashblocks-rpc.md +++ b/book/src/developers/flashblocks-rpc.md @@ -190,7 +190,7 @@ The Flashblocks RPC implementation follows this data flow: Flashblocks payloads contain the following information: -```rust +```rust,ignore pub struct FlashblocksPayloadV1 { pub version: PayloadVersion, pub execution_payload: OpExecutionPayloadEnvelope, diff --git a/book/src/modules/flashtestations.md b/book/src/modules/flashtestations.md index 83c52197..7a72d1a0 100644 --- a/book/src/modules/flashtestations.md +++ b/book/src/modules/flashtestations.md @@ -4,39 +4,39 @@ Flashtestations is a rollup-boost module that provides onchain TEE (Trusted Exec ## Architecture -``` -┌─────────────────────────┐ ┌─────────────────────┐ -│ TDX VM │ │ Onchain Verifier │ -│ │ Attestation │ │ -│ ┌─────────────────┐ │ Quote │ ┌─────────────────┐ │ -│ │ TEE Workload │ │ ───────────────► │ │ DCAP Attestation│ │ -│ │ │ │ │ │ Verifier │ │ -│ │ (measurements) │ │ │ │ │ │ -│ └─────────────────┘ │ │ └────────┬────────┘ │ -│ │ │ │ │ -└─────────────────────────┘ │ ▼ │ - │ ┌─────────────────┐ │ -┌─────────────────────────┐ │ │ Intel │ │ -│ Consumer Contract │ │ │ Endorsements │ │ -│ │ │ │ │ │ -│ ┌─────────────────┐ │ │ └────────┬────────┘ │ -│ │ Operation │ │ │ │ │ -│ │ Authorization │ │ │ ▼ │ -│ └─────────────────┘ │ │ ┌─────────────────┐ │ -│ │ │ │ │ Registration │ │ -└─────────┼───────────────┘ │ │ Logic │ │ - │ │ └────────┬────────┘ │ - │ └──────────┼──────────┘ - │ │ -┌─────────▼──────────────┐ ▼ -│ Policy │ ┌───────────────────────────┐ -│ │ isValid │ Flashtestation Registry │ -│ ┌─────────────────────┐│ Query │ │ -│ │ allowedWorkloadIds[]││ ◄───────────────►│ {teeAddress: registration}│ -│ │ {registration: ││ │ map │ -│ │ workloadId} map ││ │ │ -│ └─────────────────────┘│ └───────────────────────────┘ -└────────────────────────┘ +```text ++-------------------------+ +---------------------+ +| TDX VM | | Onchain Verifier | +| | Attestation | | +| +-----------------+ | Quote | +-----------------+ | +| | TEE Workload | | ---------------> | | DCAP Attestation| | +| | | | | | Verifier | | +| | (measurements) | | | | | | +| +-----------------+ | | +--------+--------+ | +| | | | | ++-------------------------+ | v | + | +-----------------+ | ++-------------------------+ | | Intel | | +| Consumer Contract | | | Endorsements | | +| | | | | | +| +-----------------+ | | +--------+--------+ | +| | Operation | | | | | +| | Authorization | | | v | +| +-----------------+ | | +-----------------+ | +| | | | | Registration | | ++---------+---------------+ | | Logic | | + | | +--------+--------+ | + | +----------+----------+ + | | ++---------+---------------+ v +| Policy | +---------------------------+ +| | isValid | Flashtestation Registry | +| +---------------------+ | Query | | +| | allowedWorkloadIds[]| | <--------------> | {teeAddress: registration}| +| | {registration: | | | map | +| | workloadId} map | | | | +| +---------------------+ | +---------------------------+ ++-------------------------+ ``` ### Core Components diff --git a/book/src/operators/production.md b/book/src/operators/production.md index 8d826762..c8c56662 100644 --- a/book/src/operators/production.md +++ b/book/src/operators/production.md @@ -117,7 +117,7 @@ Sets the current execution mode for `rollup-boost`. **Request**: -``` +```json { "method": "debug_setExecutionMode", "params": [ "enabled" | "dry_run" | "disabled" ], @@ -128,7 +128,7 @@ Sets the current execution mode for `rollup-boost`. **Response**: -``` +```json { "result": null, "id": 1, @@ -142,7 +142,7 @@ Retrieves the current execution mode. **Request**: -``` +```json { "method": "debug_getExecutionMode", "params": [], @@ -153,7 +153,7 @@ Retrieves the current execution mode. **Response:** -``` +```json { "result": "enabled" | "dry_run" | "disabled", "id": 1, @@ -167,7 +167,7 @@ Retrieves the current execution mode. To enable metrics, you can set the `--metrics` flag. This will start a metrics server which will run on port 9090 by default. To see the list of metrics, you can checkout metrics.rs and ping the metrics endpoint: -``` +```bash curl http://localhost:9090/metrics ``` From 115b85f1048edd618b4af747ac640d5fd9c43602 Mon Sep 17 00:00:00 2001 From: avalonche Date: Wed, 20 Aug 2025 07:11:09 +1000 Subject: [PATCH 6/8] more fixes --- book/src/SUMMARY.md | 45 ++++++++++++++---------------- book/src/architecture/README.md | 5 ++++ book/src/architecture/sidecar.md | 14 +++++++--- book/src/cli/README.md | 7 +++++ book/src/cli/flashblocks-rpc.md | 1 - book/src/cli/websocket-proxy.md | 2 -- book/src/developers/README.md | 3 ++ book/src/modules/README.md | 5 ++++ book/src/operators/README.md | 7 +++++ book/src/operators/local.md | 47 +++++++++++++++++++++----------- book/src/operators/production.md | 28 ++++++++++++++----- 11 files changed, 109 insertions(+), 55 deletions(-) create mode 100644 book/src/architecture/README.md create mode 100644 book/src/cli/README.md create mode 100644 book/src/developers/README.md create mode 100644 book/src/modules/README.md create mode 100644 book/src/operators/README.md diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index 6ca33db0..db78ac63 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -2,28 +2,23 @@ - [Introduction](./intro.md) -# Architecture - -- [External Block Building](./architecture/external-building.md) -- [Rollup Boost Sidecar](./architecture/sidecar.md) - -# Rollup Boost Modules - -- [Flashblocks](./modules/flashblocks.md) -- [Flashtestations](./modules/flashtestations.md) - -# For Rollup Operators - -- [Running Rollup Boost Locally](./operators/local.md) -- [Running Rollup Boost in Production](./operators/production.md) -- [High Availability Setup](./operators/ha-setup.md) - -# For DApp Developers - -- [Flashblocks Data over JSON RPC](./developers/flashblocks-rpc.md) - -# CLI Reference - -- [rollup-boost](./cli/rollup-boost.md) -- [websocket-proxy](./cli/websocket-proxy.md) -- [flashblocks-rpc](./cli/flashblocks-rpc.md) \ No newline at end of file +- [Architecture](architecture/README.md) + - [External Block Building](./architecture/external-building.md) + - [Rollup Boost Sidecar](./architecture/sidecar.md) + +- [Rollup Boost Modules](./modules/README.md) + - [Flashblocks](./modules/flashblocks.md) + - [Flashtestations](./modules/flashtestations.md) + +- [For Rollup Operators](./operators/README.md) + - [Running Rollup Boost Locally](./operators/local.md) + - [Running Rollup Boost in Production](./operators/production.md) + - [High Availability Setup](./operators/ha-setup.md) + +- [For DApp Developers](./developers/README.md) + - [Flashblocks Data over JSON RPC](./developers/flashblocks-rpc.md) + +- [CLI Reference](./cli/README.md) + - [rollup-boost](./cli/rollup-boost.md) + - [websocket-proxy](./cli/websocket-proxy.md) + - [flashblocks-rpc](./cli/flashblocks-rpc.md) \ No newline at end of file diff --git a/book/src/architecture/README.md b/book/src/architecture/README.md new file mode 100644 index 00000000..4b50059b --- /dev/null +++ b/book/src/architecture/README.md @@ -0,0 +1,5 @@ +# Architecture + +[External Block Building](./external-building.md) + +[Rollup Boost Sidecar](./sidecar.md) \ No newline at end of file diff --git a/book/src/architecture/sidecar.md b/book/src/architecture/sidecar.md index 704b4b95..08715a9d 100644 --- a/book/src/architecture/sidecar.md +++ b/book/src/architecture/sidecar.md @@ -59,8 +59,8 @@ sequenceDiagram By default, `rollup-boost` will proxy all RPC calls from the proposer `op-node` to its local `op-geth` node. These are the list of RPC calls that are proxied to both the proposer and the builder execution engines: -- `engine_forkchoiceUpdatedV3`: this call is only multiplexed to the builder if the call contains payload attributes and the no_tx_pool attribute is false. -- `engine_getPayloadV3`: this is used to get the builder block. +- `engine_forkchoiceUpdated`: this call is only multiplexed to the builder if the call contains payload attributes and the no_tx_pool attribute is false. +- `engine_getPayload`: this is used to get the builder block. - `miner_*`: this allows the builder to be aware of changes in effective gas price, extra data, and [DA throttling requests](https://docs.optimism.io/builders/chain-operators/configuration/batcher) from the batcher. - `eth_sendRawTransaction*`: this forwards transactions the proposer receives to the builder for block building. This call may not come from the proposer `op-node`, but directly from the rollup's rpc engine. @@ -68,5 +68,11 @@ By default, `rollup-boost` will proxy all RPC calls from the proposer `op-node` `rollup-boost` will use boost sync by default to sync directly with the proposer `op-node` via the Engine API. Boost sync improves the performance of keeping the builder in sync with the tip of the chain by removing the need to receive chain updates via p2p from the builder `op-node` once the builder is synced. This entails additional engine api calls that are multiplexed to the builder from rollup-boost: -- `engine_forkchoiceUpdatedV3`: this call will be multiplexed to the builder regardless of whether the call contains payload attributes or not. -- `engine_newPayloadV3`: ensures the builder has the latest block if the local payload was used. +- `engine_forkchoiceUpdated`: this call will be multiplexed to the builder regardless of whether the call contains payload attributes or not. +- `engine_newPayload`: ensures the builder has the latest block if the local payload was used. + +## Reorgs + +Rollup-boost remains unaffected by blockchain reorganizations due to its stateless design as a pure proxy layer between the consensus layer (op-node) and execution engines. + +When reorgs impact the sequencing epoch derivation or cause drift in the L2 chain state, rollup-boost simply proxies all Engine API calls—including fork choice updates reflecting the new canonical chain and payload requests for reorg recovery—directly to both the builder and local execution client without maintaining any state about the reorganization. The actual reorg handling, including re-deriving the correct L2 blocks from the updated sequencing windows and managing any resulting drift, is performed by the underlying execution engines (e.g op-geth, op-reth) which receive these reorg signals through the standard Engine API methods that rollup-boost forwards. \ No newline at end of file diff --git a/book/src/cli/README.md b/book/src/cli/README.md new file mode 100644 index 00000000..6d90dc01 --- /dev/null +++ b/book/src/cli/README.md @@ -0,0 +1,7 @@ +# CLI Reference + +[rollup-boost](./rollup-boost.md) + +[websocket-proxy](./websocket-proxy.md) + +[flashblocks-rpc](./flashblocks-rpc.md) \ No newline at end of file diff --git a/book/src/cli/flashblocks-rpc.md b/book/src/cli/flashblocks-rpc.md index a6453f42..41fb549d 100644 --- a/book/src/cli/flashblocks-rpc.md +++ b/book/src/cli/flashblocks-rpc.md @@ -1,6 +1,5 @@ # flashblocks-rpc - ## Command Line Options - `flashblocks.enabled`: Enable flashblocks functionality (default: false) diff --git a/book/src/cli/websocket-proxy.md b/book/src/cli/websocket-proxy.md index 5a41a901..06742c6d 100644 --- a/book/src/cli/websocket-proxy.md +++ b/book/src/cli/websocket-proxy.md @@ -1,7 +1,5 @@ # websocket-proxy -The websocket-proxy is a service - ## Command-line Options ### Connection Configuration diff --git a/book/src/developers/README.md b/book/src/developers/README.md new file mode 100644 index 00000000..da10faa2 --- /dev/null +++ b/book/src/developers/README.md @@ -0,0 +1,3 @@ +# For DApp Developers + +[Flashblocks Data over JSON RPC](./flashblocks-rpc.md) \ No newline at end of file diff --git a/book/src/modules/README.md b/book/src/modules/README.md new file mode 100644 index 00000000..ea2926e5 --- /dev/null +++ b/book/src/modules/README.md @@ -0,0 +1,5 @@ +# Rollup Boost Modules + +[Flashblocks](./flashblocks.md) + +[Flashtestations](./flashtestations.md) \ No newline at end of file diff --git a/book/src/operators/README.md b/book/src/operators/README.md new file mode 100644 index 00000000..8092d487 --- /dev/null +++ b/book/src/operators/README.md @@ -0,0 +1,7 @@ +# For Rollup Operators + +[Running Rollup Boost Locally](./local.md) + +[Running Rollup Boost in Production](./production.md) + +[High Availability Setup](./ha-setup.md) \ No newline at end of file diff --git a/book/src/operators/local.md b/book/src/operators/local.md index 98ac74ea..9ea5364b 100644 --- a/book/src/operators/local.md +++ b/book/src/operators/local.md @@ -1,6 +1,36 @@ # Running Rollup Boost Locally -To run a local development network, you can use either Kurtosis or builder-playground to spin up the op-stack with rollup boost. This would include spinning up: +To run a local development network, you can use either Kurtosis or builder-playground to spin up the op-stack with rollup boost. + +## Builder Playground + +Builder playground is a tool to deploy an end-to-end environment locally. It can be used to test both L1 and OP Stack block builders. + +This will include deploying an Op Stack chain with: + +- A complete L1 setup (CL/EL) +- A complete L2 sequencer (op-geth/op-node/op-batcher) +- Op-rbuilder as the external block builder with Flashblocks support + +```bash +builder-playground cook opstack --external-builder op-rbuilder +``` + +Flags: + +`--enable-latest-fork` (int): Enables the latest fork (isthmus) at startup (0) or n blocks after genesis. +`--flashblocks`: Enables rollup-boost with Flashblocks enabled for pre-confirmations + +In this setup, there is a prefunded test account to send test transactions at: + +- address: 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 +- private key: ac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 + +## Kurtosis + +Kurtosis is a tool to manage containerized services. To run rollup-boost in an op-stack devnet first make sure you have [just](https://github.com/casey/just), and [kurtosis-cli](https://docs.kurtosis.com/install/) installed. + +This would include spinning up: - sequencer `op-node` and `op-geth` - builder `op-node` and `op-rbuilder` @@ -8,10 +38,6 @@ To run a local development network, you can use either Kurtosis or builder-playg - ethereum l1 devnet with l2 contracts deployed - `op-proposer` and `op-batcher` -## Kurtosis - -Kurtosis is a tool to manage containerized services. To run rollup-boost in an op-stack devnet first make sure you have [just](https://github.com/casey/just), and [kurtosis-cli](https://docs.kurtosis.com/install/) installed. - Then run the following command to start the devnet: ```sh @@ -33,14 +59,3 @@ just stress-test ``` See the [optimism package](https://github.com/ethpandaops/optimism-package/blob/main/README.md#configuration) for additional configuration options. - -## Builder Playground - -Builder playground is a tool to deploy an end-to-end environment locally. It can be used to test both L1 and OP Stack block builders. - -To run a - -In this setup, there is a prefunded test account to send test transactions at: - -- address: 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 -- private key: ac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 diff --git a/book/src/operators/production.md b/book/src/operators/production.md index c8c56662..0b44004d 100644 --- a/book/src/operators/production.md +++ b/book/src/operators/production.md @@ -6,10 +6,14 @@ To run rollup boost with a regular sequencer setup, change the `--l2` flag in th To configure rollup-boost, set the l2 url to the url of the proposer auth rpc endpoint and the builder url to the builder auth rpc endpoint. Separate JWT tokens will be needed for the two endpoints. -You can also set the options using environment variables. See .env.example to use the default values. +You can also set the options using environment variables. See `.env.example` to use the default values. ```bash -cargo run --bin rollup-boost -- --l2-jwt-token your_jwt_token --l2-url http://localhost:8545 --builder-jwt-token your_jwt_token --builder-url http://localhost:8546 +cargo run --bin rollup-boost -- \ + --l2-jwt-token your_jwt_token \ + --l2-url http://localhost:8545 \ + --builder-jwt-token your_jwt_token \ + --builder-url http://localhost:8546 ``` To set up a builder, you can use [`op-rbuilder`](https://github.com/flashbots/op-rbuilder) with an op-node instance and have rollup-boost point to the builder auth rpc endpoint. @@ -173,17 +177,27 @@ curl http://localhost:9090/metrics All spans create duration histogram metrics with the name "{span_name}\_duration". Currently, this list includes: -- fork_choice_updated_v3_duration -- get_payload_v3_duration -- new_payload_v3_duration +- fork_choice_updated_duration +- get_payload_duration +- new_payload_duration + +Additionally, execution engines such as op-rbuilder has rpc metrics exposed to check if `engine_getPayloadV4` requests have been received. To check if the builder blocks are landing on-chain, the builder can be configured to include a builder transaction in the block, which is captured as part of the builder metrics. To see more details about observability in the op-builder, you can check op-rbuilder's [README](https://github.com/flashbots/op-rbuilder?tab=readme-ov-file#observability). + +#### Flashblocks + +There are metrics and observability in all the services supporting flashblocks. In rollup-boost: + +- `messages_processed` - number of messages processed from the flashblocks websocket stream +- `flashblocks_counter` - number of flashblocks proposed +- `flashblocks_missing_counter` - number of flashblocks missed from the expected number of flashblocks -Additionally, execution engines such as op-rbuilder has rpc metrics exposed to check if `engine_getPayloadV3` requests have been received. To check if the builder blocks are landing on-chain, the builder can be configured to include a builder transaction in the block, which is captured as part of the builder metrics. To see more details about observability in the op-builder, you can check op-rbuilder's [README](https://github.com/flashbots/rollup-boost?tab=readme-ov-file#rollup-boost). +Additionally, the builder transaction can also be observed in the last flashblock to determine if the number of expected flashblocks has been included onchain. ### Tracing Tracing is enabled by setting the `--tracing` flag. This will start exporting traces to the otlp endpoint specified in the `--otlp-endpoint` flag. This endpoint is set to `http://localhost:4317` by default. -Traces use the payload id to track the block building lifecycle. A distributed tracing system such as [Jaeger](https://www.jaegertracing.io/) can be used to visualize when the proposer triggers block building via `engine_forkchoiceUpdatedV3` and retrieve the block with `engine_getPayloadV3`. +Traces use the payload id to track the block building lifecycle. A distributed tracing system such as [Jaeger](https://www.jaegertracing.io/) can be used to visualize when the proposer triggers block building via `engine_forkchoiceUpdated` and retrieve the block with `engine_getPayload`. ## Troubleshooting Builder Responses From e88cbb6c1833e6820af46faf90abd953e1c11af6 Mon Sep 17 00:00:00 2001 From: avalonche Date: Thu, 21 Aug 2025 08:15:30 +1000 Subject: [PATCH 7/8] doc updates --- book/src/architecture/external-building.md | 6 +- book/src/cli/flashblocks-rpc.md | 4 +- book/src/developers/flashblocks-rpc.md | 4 +- book/src/intro.md | 67 ++++++++++++++++------ book/src/modules/flashblocks.md | 12 ++-- book/src/operators/ha-setup.md | 16 +++--- book/src/operators/local.md | 12 ++-- book/src/operators/production.md | 20 +++---- 8 files changed, 88 insertions(+), 53 deletions(-) diff --git a/book/src/architecture/external-building.md b/book/src/architecture/external-building.md index dfb06a4f..cd34c0c3 100644 --- a/book/src/architecture/external-building.md +++ b/book/src/architecture/external-building.md @@ -1,9 +1,9 @@ # External Block Building -Much like [mev-boost](https://github.com/flashbots/mev-boost) on Ethereum layer 1, rollup-boost is a sidecar run alongside the sequencer in Optimism chains to source blocks from external block builders. Unlike mev-boost, there are no code changes or extra config to support external block building in the consensus node as rollup-boost reuses the existing Engine API to source external blocks. +Much like [mev-boost](https://github.com/flashbots/mev-boost) on Ethereum layer 1, rollup-boost is a sidecar that runs alongside the sequencer in Optimism chains to source blocks from external block builders. Unlike mev-boost, there are no code changes or extra config to support external block building in the consensus node as rollup-boost reuses the existing Engine API to source external blocks. ![architecture](https://raw.githubusercontent.com/flashbots/rollup-boost/refs/heads/main/assets/rollup-boost-architecture.png) -Instead of pointing to the local execution client, the rollup operator simply needs to point the consensus node to rollup-boost and configure rollup-boost to both the local execution client and the external block builder. +Instead of pointing to the local execution client, the rollup operator simply needs to point the consensus node to rollup-boost and configure rollup-boost to connect to both the local execution client and the external block builder. -To read more about the design, check out the [design doc](https://github.com/ethereum-optimism/design-docs/blob/main/protocol/external-block-production.md) of how rollup-boost integrates into the Optimism stack. +To read more about the design, check out the [design doc](https://github.com/ethereum-optimism/design-docs/blob/main/protocol/external-block-production.md) for how rollup-boost integrates into the Optimism stack. diff --git a/book/src/cli/flashblocks-rpc.md b/book/src/cli/flashblocks-rpc.md index 41fb549d..e40548a2 100644 --- a/book/src/cli/flashblocks-rpc.md +++ b/book/src/cli/flashblocks-rpc.md @@ -2,6 +2,6 @@ ## Command Line Options -- `flashblocks.enabled`: Enable flashblocks functionality (default: false) -- `flashblocks.websocket-url`: WebSocket URL for flashblocks stream +- `flashblocks.enabled`: Enable Flashblocks functionality (default: false) +- `flashblocks.websocket-url`: WebSocket URL for Flashblocks stream - Standard reth/OP Stack options for chain and RPC configuration \ No newline at end of file diff --git a/book/src/developers/flashblocks-rpc.md b/book/src/developers/flashblocks-rpc.md index a3ed817a..45c5c009 100644 --- a/book/src/developers/flashblocks-rpc.md +++ b/book/src/developers/flashblocks-rpc.md @@ -4,7 +4,7 @@ The Flashblocks RPC implementation provides preconfirmation data through modifie ## Quick Start -To run a node capable of serving flashblocks, run the `flashblock-rpc` crate inside the rollup-boost repository. +To run a node capable of serving Flashblocks, run the `flashblocks-rpc` crate inside the rollup-boost repository. Build: @@ -174,7 +174,7 @@ Retrieves the transaction count (nonce) for an account from the pending state. **Notes:** - Returns nonce reflecting all preconfirmed transactions - Combines latest confirmed nonce with pending transaction count -- Useful for determining the next valid nonce for the next flashblock +- Useful for determining the next valid nonce for the next Flashblock ## Data Flow diff --git a/book/src/intro.md b/book/src/intro.md index 80a37929..ef7d25c3 100644 --- a/book/src/intro.md +++ b/book/src/intro.md @@ -1,24 +1,60 @@ # Rollup Boost -Rollup Boost is a lightweight sidecar for rollups that enables rollup extensions. These extensions allow for an efficient, decentralized, and verifiable block building platform for rollups. +Rollup Boost is a lightweight sidecar for rollups that enables rollup extensions. These extensions provide an efficient, decentralized, and verifiable block building platform for rollups. ## What is Rollup Boost? -[Rollup Boost](https://github.com/flashbots/rollup-boost/) uses the [Engine API](https://specs.optimism.io/protocol/exec-engine.html#engine-api) in the Optimism stack to enable its rollup extensions. This requires no modification to the OP stack software and enables rollup operators to connect to an external builder. +[Rollup Boost](https://github.com/flashbots/rollup-boost/) is a sequencer sidecar that uses the [Engine API](https://specs.optimism.io/protocol/exec-engine.html#engine-api) in the Optimism stack to enable its rollup extensions. Its scalable modules allow for faster confirmation times, stronger user guarantees, and more. + +It requires no modification to the OP stack software and allows rollup operators to connect to an external builder. It is designed and developed by [Flashbots](https://flashbots.net/) under a MIT license. We invite developers, rollup operators, and researchers to join in developing this open-source software to achieve efficiency and decentralization in the rollup ecosystem. +## Who is this for? + +Rollup Boost is designed for: + +- **Rollup Operators**: Teams running OP Stack or compatible rollups who want to improve efficiency, reduce confirmation times and have more control over block construction. + +- **Rollup Developers**: Engineers building on rollups to unlock new use cases with rollup extensions. + +- **Block Builders**: Teams focused on MEV who want to offer specialized block building services for rollups. + +- **Researchers**: Those exploring new approaches to MEV and block production strategies. + ## What are the design goals of Rollup Boost? -**Simplicity**: Rollup Boost was designed with minimal complexity, and maintaining a lightweight setup avoids additional latency. By focusing on simplicity, Rollup Boost integrates smoothly into the OP stack without disrupting existing op-node and execution engine communication. +**Simplicity** + +Rollup Boost was designed with minimal complexity, maintaining a lightweight setup that avoids additional latency. + +By focusing on simplicity, Rollup Boost integrates smoothly into the OP stack without disrupting existing op-node and execution engine communication. + +This way, we prioritize the reliability of the block proposal hot path over feature richness. We achieve this by striving for a stateless design and limit scope creep. + +**Modularity** -**Modularity**: Recognizing that rollups have varying needs, Rollup Boost was built with extensibility in mind. It is designed to support custom block-building features, allowing operators to implement modifications for any variety of block selection or customization rules. +Recognizing that rollups have varying needs, Rollup Boost was built with extensibility in mind. It is designed to support custom block-building features, allowing operators to implement modifications for custom block selection rules. -**Liveness Protection**: To safeguard against liveness risks, Rollup Boost offers a local block production fallback if there is a failure in the external builder. +**Liveness Protection** -**Compatibility**: Rollup Boost allows operators to continue using standard op-node or op-geth software without any custom forks. +To safeguard against liveness risks, Rollup Boost offers a local block production fallback if there is a failure in the external builder. -See this [doc](https://github.com/flashbots/rollup-boost/blob/main/docs/design-philosophy-testing-strategy.md) for the design philosophy and testing strategy for Rollup Boost. +Rollup Boost also guards against invalid blocks from the builder by validating the blocks against the local execution engine. This ensures the proposer always have a fallback path and minimizes liveness risks of the chain. + +All modules in Rollup Boost are designed and tested with a fallback scenario in mind to maintain high performance and uptime. + +**Compatibility** + +Rollup Boost allows operators to continue using the standard `op-node` and `op-geth` / `op-reth` software without any custom forks. + +It is also compatible with `op-conductor` when running sequencers with a high availability setup. + +It aims to be on parity with the performance of using a vanilla proposer setup without Rollup Boost. + +
+ +For more details on the design philosophy and testing strategy of Rollup Boost, see this [doc](https://github.com/flashbots/rollup-boost/blob/main/docs/design-philosophy-testing-strategy.md). ## Is it secure? @@ -26,16 +62,15 @@ Rollup Boost underwent a security audit on May 11, 2025, with [Nethermind](https In addition to the audit, we have an extensive suite of integration and kurtosis tests in our CI to ensure the whole flow works end-to-end with the OP stack as well as with external builders. -## Who is this for? +## Getting Help -Rollup Boost is designed for: +- GitHub Issues: Open an [issue](https://github.com/flashbots/rollup-boost/issues/new) for bugs or feature requests +- Forum: Join the [forum](https://collective.flashbots.net/c/rollup-boost) for development updates and research discussions -- **Rollup Operators**: Teams running OP Stack or compatible rollups who want to improve efficiency, reduce confirmation times, and have more control over block construction. -- **Rollup Developers**: Engineers building on rollups to unlock new use cases with rollup extensions. -- **Block Builders**: Teams focused on MEV who want to offer specialized block building services for rollups. -- **Researchers**: Those exploring new approaches to MEV and block production strategies. +## Sections -## Getting Help +Here are some useful sections to jump to: -- GitHub Issues: Open an [issue](https://github.com/flashbots/rollup-boost/issues/new) for bugs or feature requests -- Forum: Join the [forum](https://collective.flashbots.net/c/rollup-boost) for development updates and research topics \ No newline at end of file +- Run Rollup Boost with the full Op stack setup locally by following this [guide](./operators/local.md). +- Read about how [flashblocks](./modules/flashblocks.md) work in Rollup Boost +- Query the [JSON-RPC](./developers/flashblocks-rpc.md) of a flashblocks enabled node Foundry's `cast` or `curl`. \ No newline at end of file diff --git a/book/src/modules/flashblocks.md b/book/src/modules/flashblocks.md index 29515e95..390de7ee 100644 --- a/book/src/modules/flashblocks.md +++ b/book/src/modules/flashblocks.md @@ -10,7 +10,7 @@ The Flashblocks setup consists of three main components: - **op-rbuilder**: A builder with Flashblocks support - **op-reth**: A fallback builder (standard EL node) -It utilizes websockets to stream flashblocks from the builder to rollup-boost to minimize the latency between the flashblocks and the sequencer. +It utilizes WebSockets to stream Flashblocks from the builder to rollup-boost to minimize the latency between the Flashblocks and the sequencer. ### Flashblocks Workflow @@ -40,9 +40,9 @@ flowchart LR RPC --> Users ``` -1. **Websocket Communication**: Flashblocks utilizes websockets to stream flashblocks from the builder to rollup-boost once its constructed to minimize the latency between the flashblocks and the sequencer. -2. **Websocket Proxy**: rollup-boost caches these flashblocks and streams them to a websocket proxy. The proxy then fans out the flashblocks to downstream rpc providers. -3. **RPC Overlay**: Once RPC providers receive these flashblocks from the proxy, clients need to run a modified node that supports serving RPC requests with the flashblocks preconfirmation state. -4. **Full Block**: At the end of the slot, the proposer requests a full block from rollup-boost. If rollup-boost does not have the flashblocks cached due to a lost connection, it will fallback to the getPayload call to both the local execution client and the builder. +1. **WebSocket Communication**: Flashblocks utilizes WebSockets to stream Flashblocks from the builder to rollup-boost once it's constructed to minimize the latency between the Flashblocks and the sequencer. +2. **WebSocket Proxy**: rollup-boost caches these Flashblocks and streams them to a WebSocket proxy. The proxy then fans out the Flashblocks to downstream RPC providers. +3. **RPC Overlay**: Once RPC providers receive these Flashblocks from the proxy, clients need to run a modified node that supports serving RPC requests with the Flashblocks preconfirmation state. +4. **Full Block**: At the end of the slot, the proposer requests a full block from rollup-boost. If rollup-boost does not have the Flashblocks cached due to a lost connection, it will fall back to the getPayload call to both the local execution client and the builder. -See the [specs](https://github.com/flashbots/rollup-boost/blob/main/specs/flashblocks.md) for the full design details for flashblocks. \ No newline at end of file +See the [specs](https://github.com/flashbots/rollup-boost/blob/main/specs/flashblocks.md) for the full design details for Flashblocks. \ No newline at end of file diff --git a/book/src/operators/ha-setup.md b/book/src/operators/ha-setup.md index 8194bc26..feda8cac 100644 --- a/book/src/operators/ha-setup.md +++ b/book/src/operators/ha-setup.md @@ -12,15 +12,15 @@ See the [design doc](https://github.com/flashbots/rollup-boost/blob/main/docs/ro In high availability deployments, `op-conductor` must assess the full health of the block production path. Rollup Boost will expose a composite `/healthz` endpoint to report on both builder synchronization and payload production status. These checks allow `op-conductor` to detect degraded block building conditions and make informed leadership decisions. -Rollup Boost will continuously monitors two independent conditions to inform the health of the builder and the default execution client: +Rollup Boost will continuously monitor two independent conditions to inform the health of the builder and the default execution client: - **Builder Synchronization**: - A background task periodically queries the builder’s latest unsafe block via `engine_getBlockByNumber`. The task compares the timestamp of the returned block to the local system time. If the difference exceeds a configured maximum unsafe interval (`max_unsafe_interval`), the builder is considered out of sync. Failure to fetch a block from the builder or detection of an outdated block timestamp results in the health status being downgraded to Partial. If the builder is responsive and the block timestamp is within the acceptable interval, the builder is considered synchronized and healthy. Alternatively instead of periodic polling, builder synchronization can be inferred if the builder returns a `VALID` response to a `newPayload` call forwarded from Rollup Boost. + A background task periodically queries the builder’s latest unsafe block via `engine_getBlockByNumber`. The task compares the timestamp of the returned block to the local system time. If the difference exceeds a configured maximum unsafe interval (`max_unsafe_interval`), the builder is considered out of sync. Failure to fetch a block from the builder or detection of an outdated block timestamp results in the health status being downgraded to Partial. If the builder is responsive and the block timestamp is within the acceptable interval, the builder is considered synchronized and healthy. Alternatively, instead of periodic polling, builder synchronization can be inferred if the builder returns a `VALID` response to a `newPayload` call forwarded from Rollup Boost. - **Payload Production**: During each `get_payload` request, Rollup Boost will verify payload availability from both the builder and the execution client. If the builder fails to deliver a payload, Rollup Boost will report partial health. If the execution client fails to deliver a payload, Rollup Boost will report unhealthy. -`op-conductor` should also be configurable in how it interprets health status for failover decisions. This allows chain operators to define thresholds based on their risk tolerance and operational goals. For example, operators may choose to maintain leadership with a sequencer reporting `206 Partial Content` to avoid unnecessary fail overs or they may configure `op-conductor` to immediately fail over when any degradation is detected. This flexibility allows the chain operator to configure a failover policy that aligns with network performance expectations and builder reliability. +`op-conductor` should also be configurable in how it interprets health status for failover decisions. This allows chain operators to define thresholds based on their risk tolerance and operational goals. For example, operators may choose to maintain leadership with a sequencer reporting `206 Partial Content` to avoid unnecessary failovers or they may configure `op-conductor` to immediately fail over when any degradation is detected. This flexibility allows the chain operator to configure a failover policy that aligns with network performance expectations and builder reliability.
@@ -42,9 +42,9 @@ During normal operation and leadership transfers, `op-conductor` should prioriti 1. Prefer nodes reporting `200 OK`. 2. Nodes that return `503 Service Unavailable` are treated as unhealthy and must not be eligible for sequencer leadership. `op-conductor` should offer a configuration option to treat nodes returning `206 Partial Content` as either healthy or unhealthy. -Rollup Boost instances that are not actively sequencing rely on the builder sync check to report health, as they are not producing blocks. This behavior mirrors the existing `op-conductor` health checks for inactive sequencers and ensures readiness during failover without compromising network liveness guarantees. Note that `op-conductor` will still evaluate existing sequencer health checks to determine overall sequencer health. +Rollup Boost instances that are not actively sequencing rely on the builder sync check to report health, as they are not producing blocks. This behavior mirrors the existing `op-conductor` health checks for inactive sequencers and ensures readiness during failover without compromising network liveness guarantees. Note that `op-conductor` will still evaluate existing sequencer health checks to determine overall sequencer health. -Note that in the case where the builder is unhealthy, `rollup-boost` should bypass forwarding block production requests to the builder entirely and immediately use the default execution client for payload construction. This avoids introducing unnecessary latency to wait for the builder response to timeout. +Note that in the case where the builder is unhealthy, `rollup-boost` should bypass forwarding block production requests to the builder entirely and immediately use the default execution client for payload construction. This avoids introducing unnecessary latency while waiting for the builder response to timeout. When builder health is restored, normal request forwarding and payload selection behavior will resume. @@ -56,9 +56,9 @@ Below is a high level summary of how each failure scenario is handled. All exist | Failure Scenario | Category | Scenario and Solution | | --- | --- | --- | -| Leader Sequencer Execution Client Fails | Sequencer Failure | `op-conductor` will detect an unhealthy status from both `rollup-boost` and pre-existing sequencer health checks, causing Conductor to elect a new leader. Once the default execution client has recovered, `rollup-boost` will update it's health status to `200` and the sequencer will continue operating normally as a follower. | -| Follower Sequencer Execution Client Fails | Sequencer Failure | Both `rollup-boost` and pre-existing sequencer health checks will report "unhealthy". Once the default exectuion client has recovered, `rollup-boost` will update it's health status to `200` and the sequencer will continue operating normally as a follower. In the event of leadership transfer, this sequencer instance will not be considered for leadership.| -| Leader `rollup-boost` Fails | Rollup Boost Failure | Leader sequencer `rollup-boost` becomes unhealthy, causing `op-conductor`s sequencer health checks to fail and attempt to elect a new leader. This failure mode is the same as a typical leader sequencer failure. Once the sequencer recovers, it will continue to participate in the cluster as a follower| +| Leader Sequencer Execution Client Fails | Sequencer Failure | `op-conductor` will detect an unhealthy status from both `rollup-boost` and pre-existing sequencer health checks, causing Conductor to elect a new leader. Once the default execution client has recovered, `rollup-boost` will update its health status to `200` and the sequencer will continue operating normally as a follower. | +| Follower Sequencer Execution Client Fails | Sequencer Failure | Both `rollup-boost` and pre-existing sequencer health checks will report "unhealthy". Once the default execution client has recovered, `rollup-boost` will update its health status to `200` and the sequencer will continue operating normally as a follower. In the event of leadership transfer, this sequencer instance will not be considered for leadership.| +| Leader `rollup-boost` Fails | Rollup Boost Failure | Leader sequencer `rollup-boost` becomes unhealthy, causing `op-conductor`'s sequencer health checks to fail and attempt to elect a new leader. This failure mode is the same as a typical leader sequencer failure. Once the sequencer recovers, it will continue to participate in the cluster as a follower| | Follower `rollup-boost` Fails | Rollup Boost Failure | Follower sequencer `rollup-boost` becomes unhealthy. The leader sequencer is unaffected. Once the sequencer recovers, it will continue to participate in the cluster as a follower.| | Leader Builder Stops Producing Blocks | Builder Failure | The builder associated with the sequencer leader stops producing new payloads. `rollup-boost` will detect the builder failure via background health checks and downgrade its health status to partial. This will result in `rollup-boost` ignoring the builder and selecting the default execution client's payload for block production. If `op-conductor` is configured to failover upon partial `rollup-boost` health, a new leader will attempt to be elected. Once the builder recovers and resumes payload production, `rollup-boost` will update its health to `200` and resume with normal operation. | | Leader Builder Falls Out of Sync | Builder Failure | The builder associated with the sequencer leader falls out of sync with the chain head. `rollup-boost` will detect the unsynced state via the background health checks and downgrade its health status to partial. This will result in `rollup-boost` ignoring builder payloads and selecting the default execution client payload for block until the builder is resynced. If `op-conductor` is configured to failover upon partial `rollup-boost` health, a new leader will attempt to be elected. Once the builder recovers, `rollup-boost` will update its health to `200` and resume with normal operation. | diff --git a/book/src/operators/local.md b/book/src/operators/local.md index 9ea5364b..b9c3f959 100644 --- a/book/src/operators/local.md +++ b/book/src/operators/local.md @@ -1,12 +1,12 @@ # Running Rollup Boost Locally -To run a local development network, you can use either Kurtosis or builder-playground to spin up the op-stack with rollup boost. +To run a local development network, you can use either Kurtosis or builder-playground to spin up the op-stack with rollup-boost. ## Builder Playground -Builder playground is a tool to deploy an end-to-end environment locally. It can be used to test both L1 and OP Stack block builders. +Builder playground is a tool to deploy an end-to-end block builder environment locally. It can be used to test both L1 and OP Stack block builders. -This will include deploying an Op Stack chain with: +This will include deploying an OP Stack chain with: - A complete L1 setup (CL/EL) - A complete L2 sequencer (op-geth/op-node/op-batcher) @@ -21,14 +21,14 @@ Flags: `--enable-latest-fork` (int): Enables the latest fork (isthmus) at startup (0) or n blocks after genesis. `--flashblocks`: Enables rollup-boost with Flashblocks enabled for pre-confirmations -In this setup, there is a prefunded test account to send test transactions at: +In this setup, there is a prefunded test account to send test transactions to: - address: 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 - private key: ac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 ## Kurtosis -Kurtosis is a tool to manage containerized services. To run rollup-boost in an op-stack devnet first make sure you have [just](https://github.com/casey/just), and [kurtosis-cli](https://docs.kurtosis.com/install/) installed. +Kurtosis is a tool to manage containerized services. To run rollup-boost in an op-stack devnet, first make sure you have [just](https://github.com/casey/just) and [kurtosis-cli](https://docs.kurtosis.com/install/) installed. This would include spinning up: @@ -50,7 +50,7 @@ To stop the devnet run: just devnet-down ``` -To run a stress test against the devnet with [contender](https://github.com/flashbots/contender) first make sure you have docker installed. +To run a stress test against the devnet with [contender](https://github.com/flashbots/contender), first make sure you have Docker installed. Then run the following command: diff --git a/book/src/operators/production.md b/book/src/operators/production.md index 0b44004d..59af4de8 100644 --- a/book/src/operators/production.md +++ b/book/src/operators/production.md @@ -2,9 +2,9 @@ ## Regular Sequencer Setup -To run rollup boost with a regular sequencer setup, change the `--l2` flag in the proposer `op-node` to point to the rollup boost rpc endpoint. +To run rollup-boost with a regular sequencer setup, change the `--l2` flag in the proposer `op-node` to point to the rollup-boost RPC endpoint. -To configure rollup-boost, set the l2 url to the url of the proposer auth rpc endpoint and the builder url to the builder auth rpc endpoint. Separate JWT tokens will be needed for the two endpoints. +To configure rollup-boost, set the L2 URL to the URL of the proposer auth RPC endpoint and the builder URL to the builder auth RPC endpoint. Separate JWT tokens will be needed for the two endpoints. You can also set the options using environment variables. See `.env.example` to use the default values. @@ -16,7 +16,7 @@ cargo run --bin rollup-boost -- \ --builder-url http://localhost:8546 ``` -To set up a builder, you can use [`op-rbuilder`](https://github.com/flashbots/op-rbuilder) with an op-node instance and have rollup-boost point to the builder auth rpc endpoint. +To set up a builder, you can use [`op-rbuilder`](https://github.com/flashbots/op-rbuilder) with an op-node instance and have rollup-boost point to the builder auth RPC endpoint. ## Flashblocks @@ -169,7 +169,7 @@ Retrieves the current execution mode. ### Metrics -To enable metrics, you can set the `--metrics` flag. This will start a metrics server which will run on port 9090 by default. To see the list of metrics, you can checkout metrics.rs and ping the metrics endpoint: +To enable metrics, you can set the `--metrics` flag. This will start a metrics server which will run on port 9090 by default. To see the list of metrics, you can check out metrics.rs and ping the metrics endpoint: ```bash curl http://localhost:9090/metrics @@ -181,17 +181,17 @@ All spans create duration histogram metrics with the name "{span_name}\_duration - get_payload_duration - new_payload_duration -Additionally, execution engines such as op-rbuilder has rpc metrics exposed to check if `engine_getPayloadV4` requests have been received. To check if the builder blocks are landing on-chain, the builder can be configured to include a builder transaction in the block, which is captured as part of the builder metrics. To see more details about observability in the op-builder, you can check op-rbuilder's [README](https://github.com/flashbots/op-rbuilder?tab=readme-ov-file#observability). +Additionally, execution engines such as op-rbuilder have RPC metrics exposed to check if `engine_getPayloadV4` requests have been received. To check if the builder blocks are landing on-chain, the builder can be configured to include a builder transaction in the block, which is captured as part of the builder metrics. To see more details about observability in the op-builder, you can check op-rbuilder's [README](https://github.com/flashbots/op-rbuilder?tab=readme-ov-file#observability). #### Flashblocks -There are metrics and observability in all the services supporting flashblocks. In rollup-boost: +There are metrics and observability in all the services supporting Flashblocks. In rollup-boost: -- `messages_processed` - number of messages processed from the flashblocks websocket stream -- `flashblocks_counter` - number of flashblocks proposed -- `flashblocks_missing_counter` - number of flashblocks missed from the expected number of flashblocks +- `messages_processed` - number of messages processed from the Flashblocks WebSocket stream +- `flashblocks_counter` - number of Flashblocks proposed +- `flashblocks_missing_counter` - number of Flashblocks missed from the expected number of Flashblocks -Additionally, the builder transaction can also be observed in the last flashblock to determine if the number of expected flashblocks has been included onchain. +Additionally, the builder transaction can also be observed in the last Flashblock to determine if the number of expected Flashblocks has been included on-chain. ### Tracing From 783f1f6ed1c767f8f96b9d1e58ce1fd67aa49732 Mon Sep 17 00:00:00 2001 From: avalonche Date: Thu, 21 Aug 2025 08:30:23 +1000 Subject: [PATCH 8/8] fix lint --- Cargo.lock | 4 ++-- crates/flashblocks-rpc/src/flashblocks.rs | 8 ++++---- crates/flashblocks-rpc/src/rpc.rs | 8 ++++---- 3 files changed, 10 insertions(+), 10 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index 9990c8a4..ed64eba3 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -11801,9 +11801,9 @@ checksum = "c1e9a774a6c28142ac54bb25d25562e6bcf957493a184f15ad4eebccb23e410a" [[package]] name = "slab" -version = "0.4.10" +version = "0.4.11" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "04dc19736151f35336d325007ac991178d504a119863a2fcb3758cdb5e52c50d" +checksum = "7a2ae44ef20feb57a68b23d846850f861394c2e02dc425a50098ae8c90267589" [[package]] name = "smallvec" diff --git a/crates/flashblocks-rpc/src/flashblocks.rs b/crates/flashblocks-rpc/src/flashblocks.rs index 689d7ea5..fe3e3c42 100644 --- a/crates/flashblocks-rpc/src/flashblocks.rs +++ b/crates/flashblocks-rpc/src/flashblocks.rs @@ -124,10 +124,10 @@ fn try_decode_message(bytes: &[u8]) -> eyre::Result { } fn try_parse_message(bytes: &[u8]) -> eyre::Result { - if let Ok(text) = String::from_utf8(bytes.to_vec()) { - if text.trim_start().starts_with("{") { - return Ok(text); - } + if let Ok(text) = String::from_utf8(bytes.to_vec()) + && text.trim_start().starts_with("{") + { + return Ok(text); } let mut decompressor = brotli::Decompressor::new(bytes, 4096); diff --git a/crates/flashblocks-rpc/src/rpc.rs b/crates/flashblocks-rpc/src/rpc.rs index d1aa8dcb..93149d43 100644 --- a/crates/flashblocks-rpc/src/rpc.rs +++ b/crates/flashblocks-rpc/src/rpc.rs @@ -113,10 +113,10 @@ where debug!("get_balance: {:?}, {:?}", address, block_number); let block_id = block_number.unwrap_or_default(); - if block_id.is_pending() { - if let Some(balance) = self.flashblocks_api.get_balance(address).await { - return Ok(balance); - } + if block_id.is_pending() + && let Some(balance) = self.flashblocks_api.get_balance(address).await + { + return Ok(balance); } EthState::balance(&self.eth_api, address, block_number) .await