Rollup Boost Docs Page

.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

.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"

book/book.toml

@@ -16,5 +16,8 @@ no-section-label = true
 enable = true
 level = 1
 
+[preprocessor.mermaid]
+command = "mdbook-mermaid"
+
 [build]
 build-dir = "book"

book/src/SUMMARY.md

@@ -1,3 +1,24 @@
-# Summary
+# Table of Contents
 
-- [Introduction](./README.md)
+- [Introduction](./intro.md)
+
+- [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)

book/src/architecture/README.md

@@ -0,0 +1,5 @@
+# Architecture
+
+[External Block Building](./external-building.md)
+
+[Rollup Boost Sidecar](./sidecar.md)

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 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 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) for how rollup-boost integrates into the Optimism stack.

book/src/architecture/sidecar.md

@@ -0,0 +1,78 @@
+# Architecture Overview
+
+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.
+   - 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
+%%{init: {'theme': 'base', 'themeVariables': { 'background': '#f4f4f4', 'primaryColor': '#2c3e50', 'primaryTextColor': '#ffffff', 'primaryBorderColor': '#34495e', 'lineColor': '#34495e', 'secondaryColor': '#ecf0f1', 'tertiaryColor': '#bdc3c7'}}}%%
+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_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.
+
+### Boost Sync
+
+`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_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.

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)

book/src/cli/flashblocks-rpc.md

@@ -0,0 +1,7 @@
+# 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

book/src/cli/rollup-boost.md

@@ -0,0 +1,19 @@
+# rollup-boost
+
+### Command-line Options
+
+- `--l2-jwt-token <TOKEN>`: JWT token for L2 authentication (required)
+- `--l2-jwt-path <PATH>`: Path to the L2 JWT secret file (required if `--l2-jwt-token` is not provided)
+- `--l2-url <URL>`: URL of the local L2 execution engine (required)
+- `--builder-url <URL>`: URL of the builder execution engine (required)
+- `--builder-jwt-token <TOKEN>`: JWT token for builder authentication (required)
+- `--builder-jwt-path <PATH>`: Path to the builder JWT secret file (required if `--builder-jwt-token` is not provided)
+- `--rpc-host <HOST>`: Host to run the server on (default: 127.0.0.1)
+- `--rpc-port <PORT>`: Port to run the server on (default: 8081)
+- `--tracing`: Enable tracing (default: false)
+- `--log-level <LEVEL>`: Log level (default: info)
+- `--log-format <FORMAT>`: Log format (default: text)
+- `--metrics`: Enable metrics (default: false)
+- `--metrics-host <METRICS_HOST>`: Host to run the metrics server on (default: 127.0.0.1)
+- `--debug-host <HOST>`: Host to run the server on (default: 127.0.0.1)
+- `--debug-server-port <PORT>`: Port to run the debug server on (default: 5555)

book/src/cli/websocket-proxy.md

@@ -0,0 +1,49 @@
+# websocket-proxy
+
+## Command-line Options
+
+### Connection Configuration
+
+- `--listen-addr <ADDRESS>`: The address and port to listen on for incoming connections (default: 0.0.0.0:8545)
+- `--upstream-ws <URI>`: WebSocket URI of the upstream server to connect to (required, can specify multiple with comma separation)
+
+### Rate Limiting
+
+- `--instance-connection-limit <LIMIT>`: Maximum number of concurrently connected clients per instance (default: 100)
+- `--per-ip-connection-limit <LIMIT>`: Maximum number of concurrently connected clients per IP (default: 10)
+- `--redis-url <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>`: Prefix for Redis keys (default: flashblocks)
+
+### Message Handling
+
+- `--message-buffer-size <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>`: Header to use to determine the client's origin IP (default: X-Forwarded-For)
+
+### Authentication
+
+- `--api-keys <KEYS>`: API keys to allow in format `<app1>:<apiKey1>,<app2>:<apiKey2>`. If not provided, the endpoint will be unauthenticated
+
+### Logging
+
+- `--log-level <LEVEL>`: Log level (default: info)
+- `--log-format <FORMAT>`: Format for logs, can be json or text (default: text)
+
+### Metrics
+
+- `--metrics`: Enable Prometheus metrics (default: true)
+- `--metrics-addr <ADDRESS>`: Address to run the metrics server on (default: 0.0.0.0:9000)
+- `--metrics-global-labels <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 <MS>`: Maximum backoff allowed for upstream connections in milliseconds (default: 20000)
+- `--subscriber-ping-interval-ms <MS>`: Interval in milliseconds between ping messages sent to upstream servers to detect unresponsive connections (default: 2000)
+- `--subscriber-pong-timeout-ms <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 <MS>`: Interval in milliseconds to send ping messages to clients (default: 15000)
+- `--client-pong-timeout-ms <MS>`: Timeout in milliseconds to wait for pong response from clients (default: 30000)

book/src/developers/README.md

@@ -0,0 +1,3 @@
+# For DApp Developers
+
+[Flashblocks Data over JSON RPC](./flashblocks-rpc.md)