{"id":20433848,"url":"https://github.com/flashbots/rollup-boost","last_synced_at":"2025-10-26T20:14:14.051Z","repository":{"id":259528138,"uuid":"859980117","full_name":"flashbots/rollup-boost","owner":"flashbots","description":"Sidecar to Enable Rollup Extensions","archived":false,"fork":false,"pushed_at":"2025-04-04T08:08:33.000Z","size":1305,"stargazers_count":109,"open_issues_count":28,"forks_count":32,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-04-04T08:30:36.258Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://writings.flashbots.net/introducing-rollup-boost","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/flashbots.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-09-19T15:53:40.000Z","updated_at":"2025-04-03T17:13:19.000Z","dependencies_parsed_at":"2024-10-26T08:14:44.152Z","dependency_job_id":"8e710c8d-8ed5-4382-af21-9af315d1a895","html_url":"https://github.com/flashbots/rollup-boost","commit_stats":{"total_commits":33,"total_committers":5,"mean_commits":6.6,"dds":"0.21212121212121215","last_synced_commit":"feef2c2c7b28a03c05439012bcefc6be866fb11a"},"previous_names":["flashbots/rollup-boost"],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flashbots%2Frollup-boost","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flashbots%2Frollup-boost/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flashbots%2Frollup-boost/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flashbots%2Frollup-boost/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/flashbots","download_url":"https://codeload.github.com/flashbots/rollup-boost/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247345849,"owners_count":20924102,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-15T08:21:47.786Z","updated_at":"2025-10-26T20:14:14.042Z","avatar_url":"https://github.com/flashbots.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Rollup Boost banner](./assets/Rollup-Boost_brand-assets/rollup-boost_banner.png)\n\n[![Test status](https://github.com/flashbots/rollup-boost/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/flashbots/rollup-boost/actions?query=workflow%3A%22Tests%22)\n\n# Rollup Boost\n\nRollup Boost is a block builder sidecar for Optimism Stack chains to enable external block production. 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).\n\n## Usage\n\nRun the rollup-boost server using the following command:\n\n```\ncargo run --bin rollup-boost -- [OPTIONS]\n```\n\n### Command-line Options\n\n- `--l2-jwt-token \u003cTOKEN\u003e`: JWT token for L2 authentication (required)\n- `--l2-jwt-path \u003cPATH\u003e`: Path to the L2 JWT secret file (required if `--l2-jwt-token` is not provided)\n- `--l2-url \u003cURL\u003e`: URL of the local L2 execution engine (required)\n- `--builder-url \u003cURL\u003e`: URL of the builder execution engine (required)\n- `--builder-jwt-token \u003cTOKEN\u003e`: JWT token for builder authentication (required)\n- `--builder-jwt-path \u003cPATH\u003e`: Path to the builder JWT secret file (required if `--builder-jwt-token` is not provided)\n- `--rpc-host \u003cHOST\u003e`: Host to run the server on (default: 127.0.0.1)\n- `--rpc-port \u003cPORT\u003e`: Port to run the server on (default: 8081)\n- `--tracing`: Enable tracing (default: false)\n- `--log-level \u003cLEVEL\u003e`: Log level (default: info)\n- `--log-format \u003cFORMAT\u003e`: Log format (default: text)\n- `--metrics`: Enable metrics (default: false)\n- `--metrics-host \u003cMETRICS_HOST\u003e`: Host to run the metrics server on (default: 127.0.0.1)\n- `--debug-host \u003cHOST\u003e`: Host to run the server on (default: 127.0.0.1)\n- `--debug-server-port \u003cPORT\u003e`: Port to run the debug server on (default: 5555)\n\n### Environment Variables\n\nYou can also set the options using environment variables. See .env.example to use the default values.\n\n### Example\n\n```\ncargo 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\n```\n\n## Core System Workflow\n\n1. `rollup-boost` receives an `engine_FCU` with the attributes to initiate block building:\n   - It relays the call to proposer `op-geth` as usual and multiplexes the call to builder.\n   - 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.\n2. When `rollup-boost` receives an `engine_getPayload`:\n   - It queries proposer `op-geth` for a fallback block.\n   - In parallel, it queries builder for a block.\n3. Upon receiving the builder block:\n   - `rollup-boost` validates the block with proposer `op-geth` using `engine_newPayload`.\n   - This validation ensures the block will be valid for proposer `op-geth`, preventing network stalls due to invalid blocks.\n   - If the external block is valid, it is returned to the proposer `op-node`. Otherwise, `rollup-boost` will return the fallback block.\n4. The proposer `op-node` sends a `engine_newPayload` request to `rollup-boost` and another `engine_FCU` without attributes to update chain state.\n   - `rollup-boost` just relays the calls to proposer `op-geth`.\n   - 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.\n   - The builder `op-node` will receive blocks via p2p gossip and keep the builder node in sync via the engine api.\n\n```mermaid\nsequenceDiagram\n    box Proposer\n        participant op-node\n        participant rollup-boost\n        participant op-geth\n    end\n    box Builder\n        participant builder-op-node as op-node\n        participant builder-op-geth as builder\n    end\n\n    Note over op-node, builder-op-geth: 1. Triggering Block Building\n    op-node-\u003e\u003erollup-boost: engine_FCU (with attrs)\n    rollup-boost-\u003e\u003eop-geth: engine_FCU (with attrs)\n    rollup-boost-\u003e\u003ebuilder-op-geth: engine_FCU (with attrs)\n    rollup-boost-\u003e\u003eop-node: proposer payload id\n\n    Note over op-node, builder-op-geth: 2. Get Local and Builder Blocks\n    op-node-\u003e\u003erollup-boost: engine_getPayload\n    rollup-boost-\u003e\u003eop-geth: engine_getPayload\n    rollup-boost-\u003e\u003ebuilder-op-geth: engine_getPayload\n\n    Note over op-node, builder-op-geth: 3. Validating and Returning Builder Block\n    rollup-boost-\u003e\u003eop-geth: engine_newPayload\n    op-geth-\u003e\u003erollup-boost: block validity\n    rollup-boost-\u003e\u003eop-node: block payload\n\n    Note over op-node, builder-op-geth: 4. Updating Chain State\n    op-node-\u003e\u003erollup-boost: engine_newPayload\n    rollup-boost-\u003e\u003eop-geth: engine_newPayload\n    op-node-\u003e\u003erollup-boost: engine_FCU (without attrs)\n    rollup-boost-\u003e\u003eop-geth: engine_FCU (without attrs)\n```\n\n## RPC Calls\n\nBy 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:\n\n- `engine_forkchoiceUpdatedV3`: this call is only multiplexed to the builder if the call contains payload attributes and the no_tx_pool attribute is false.\n- `engine_getPayloadV3`: this is used to get the builder block.\n- `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.\n- `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.\n\n## Debug API\n\nThe Debug API is a JSON-RPC API that can be used to configure rollup-boost's execution mode. The execution mode determines how rollup-boost makes requests to the builder:\n\n- `enabled`: The builder receives all the engine API calls from rollup-boost.\n- `dry-run`: The builder receives all the engine API calls from rollup-boost except for the get payload request.\n- `disabled`: The builder does not receive any engine API calls from rollup-boost. This allows rollup-boost to stop sending requests to the builder during runtime without needing a restart.\n\nBy default, the debug server runs on port 5555.\n\n### Specification\n\nThe debug API implements the following methods:\n\n#### `debug_setExecutionMode`\n\nSets the execution mode of rollup-boost.\n\n**Params**\n\n- execution_mode: The new execution mode (available options 'dry_run', 'enabled' or 'disabled').\n\n**Returns**\n\n- `execution_mode`: The new execution mode.\n\n**Example**\n\nTo set dry run mode:\n\n```bash\ncurl -X POST -H \"Content-Type: application/json\" --data '{\n    \"jsonrpc\": \"2.0\",\n    \"id\": 1,\n    \"method\": \"debug_setExecutionMode\",\n    \"params\": [{\"execution_mode\":\"dry_run\"}]\n}' http://localhost:5555\n```\n\nTo disable rollup-boost calls to the builder:\n\n```bash\ncurl -X POST -H \"Content-Type: application/json\" --data '{\n    \"jsonrpc\": \"2.0\",\n    \"id\": 1,\n    \"method\": \"debug_setExecutionMode\",\n    \"params\": [{\"execution_mode\":\"disabled\"}]\n}' http://localhost:5555\n```\n\n#### `debug_getExecutionMode`\n\nGets the current execution mode of rollup-boost.\n\n**Params**\n\nNone\n\n**Returns**\n\n- `execution_mode`: The current execution mode.\n\n**Example**\n\n```bash\ncurl -X POST -H \"Content-Type: application/json\" --data '{\n    \"jsonrpc\": \"2.0\",\n    \"id\": 1,\n    \"method\": \"debug_getExecutionMode\",\n    \"params\": []\n}' http://localhost:5555\n```\n\n### Debug Command\n\n`rollup-boost` also includes a debug command to interact with the debug API from rollup-boost.\n\nThis is useful for testing interactions with external block builders in a production environment without jeopardizing OP stack liveness, especially for network upgrades.\n\n### Usage\n\nTo run rollup-boost in debug mode with a specific execution mode, you can use the following command:\n\n```\nrollup-boost debug set-execution-mode [enabled|dry-run|disabled]\n```\n\n## Maintainers\n\n- [@avalonche](https://github.com/avalonche)\n- [@ferranbt](https://github.com/ferranbt)\n- [@0xOsiris](https://github.com/0xOsiris)\n- [@0xKitsune](https://github.com/0xKitsune)\n- [Eric Woolsey](https://github.com/0xForerunner)\n\n### Rollup Boost Devnet\n\nTo 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.\n\nThen run the following command to start the devnet:\n\n```sh\njust kurtosis-devnet-up\n```\n\nTo stop the devnet run:\n\n```sh\njust kurtosis-devnet-down\n```\n\nTo run a stress test against the devnet with [contender](https://github.com/flashbots/contender) first make sure you have docker installed.\n\nThen run the following command:\n\n```sh\njust kurtosis-stress-test\n```\n\n## License\n\nThe code in this project is free software under the [MIT License](/LICENSE).\n\n---\n\nMade with ☀️ by the ⚡🤖 collective.\n\n🎨 For Rollup Boost brand guidelines and to download brand assets, [click here](https://desert-shelf-a90.notion.site/Rollup-Boost-Brand-Guide-1c08490ae44f80ecaafee5975f71228f).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflashbots%2Frollup-boost","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fflashbots%2Frollup-boost","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflashbots%2Frollup-boost/lists"}