https://github.com/flashbots/op-rbuilder
https://github.com/flashbots/op-rbuilder
Last synced: 5 days ago
JSON representation
- Host: GitHub
- URL: https://github.com/flashbots/op-rbuilder
- Owner: flashbots
- License: apache-2.0
- Created: 2025-05-12T08:26:19.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2026-06-01T15:13:36.000Z (7 days ago)
- Last Synced: 2026-06-01T17:12:26.048Z (7 days ago)
- Language: Rust
- Size: 3.35 MB
- Stars: 51
- Watchers: 9
- Forks: 64
- Open Issues: 19
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE-APACHE
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
Awesome Lists containing this project
README
# op-rbuilder
[](https://github.com/flashbots/op-rbuilder/actions)
`op-rbuilder` is a Rust-based block builder designed to build blocks for the Optimism stack.
## Running op-rbuilder
To run op-rbuilder with the op-stack, you need:
- CL node to sync the op-rbuilder with the canonical chain
- Sequencer with the [rollup-boost](https://github.com/flashbots/rollup-boost) setup
To run the op-rbuilder, run:
```bash
cargo run -p op-rbuilder --bin op-rbuilder -- node \
--chain /path/to/chain-config.json \
--http \
--authrpc.port 9551 \
--authrpc.jwtsecret /path/to/jwt.hex
```
To build the op-rbuilder, run:
```bash
cargo build -p op-rbuilder --bin op-rbuilder
```
### Flashblocks
To run op-rbuilder with flashblocks:
```bash
cargo run -p op-rbuilder --bin op-rbuilder -- node \
--chain /path/to/chain-config.json \
--http \
--authrpc.port 9551 \
--authrpc.jwtsecret /path/to/jwt.hex \
--flashblocks.port 1111 \ # port to bind ws that provides flashblocks
--flashblocks.addr 127.0.0.1 # address to bind the ws that provides flashblocks
```
#### Flashblocks Number Contract
To enable builder tranctions to the [flashblocks number contract](https://github.com/Uniswap/flashblocks_number_contract) for contracts to integrate with flashblocks onchain, specify the address in the CLI args:
```bash
cargo run -p op-rbuilder --bin op-rbuilder -- node \
--chain /path/to/chain-config.json \
--http \
--authrpc.port 9551 \
--authrpc.jwtsecret /path/to/jwt.hex \
--flashblocks.number-contract-address 0xFlashblocksNumberAddress
```
This will increment the flashblock number before the start of every flashblock and replace the builder tx at the end of the block.
### Flashtestations
To run op-rbuilder with flashtestations:
```bash
cargo run -p op-rbuilder --bin op-rbuilder -- node \
--chain /path/to/chain-config.json \
--http \
--authrpc.port 9551 \
--authrpc.jwtsecret /path/to/jwt.hex \
--flashtestations.enabled \
--flashtestations.rpc-url your-rpc-url \ # rpc to submit the attestation transaction to
--flashtestations.funding-amount 0.01 \ # amount in ETH to fund the TEE generated key
--flashtestations.funding-key secret-key \ # funding key for the TEE key
--flashtestations.registry-address 0xFlashtestationsRegistryAddress \
--flashtestations.builder-policy-address 0xBuilderPolicyAddress
```
Note that `--rollup.builder-secret-key` must be set and funded in order for the flashtestations key to be funded and submit the attestation on-chain.
## Observability
To verify whether a builder block has landed on-chain, you can add the `--rollup.builder-secret-key` flag or `BUILDER_SECRET_KEY` environment variable.
This will add an additional transaction to the end of the block from the builder key. The transaction will have `Block Number: {}` in the input data as a transfer to the zero address. Ensure that the key has sufficient balance to pay for the transaction at the end of the block.
To enable metrics, set the `--metrics` flag like in [reth](https://reth.rs/run/monitoring) which will expose reth metrics in addition to op-rbuilder metrics. op-rbuilder exposes on-chain metrics via [reth execution extensions](https://reth.rs/exex/overview) such as the number of blocks landed and builder balance. Note that the accuracy of the on-chain metrics will be dependent on the sync status of the builder node. There are also additional block building metrics such as:
- Block building latency
- State root calculation latency
- Transaction fetch latency
- Transaction simulation latency
- Number of transactions included in the built block
To see the full list of op-rbuilder metrics, see [`src/metrics.rs`](./crates/op-rbuilder/src/metrics.rs).
Default `debug` level trace logs can be found at:
- `~/.cache/op-rbuilder/logs` on Linux
- `~/Library/Caches/op-rbuilder/logs` on macOS
- `%localAppData%/op-rbuilder/logs` on Windows
## Testing
You can run op-rbuilder's test suite using the command
```bash
make test
```
This runs both unit tests and integration tests.
## Local Devnet
Local development environment setup and configuration files can be found in [`local-testing/README.md`](./local-testing/README.md).
## Running GitHub actions locally
To verify that CI will allow your PR to be merged before sending it please make sure that our GitHub `checks.yaml` action passes locall by calling:
```
act -W .github/workflows/checks.yaml
```
More instructions on installing and configuring `act` can be found on [their website](https://nektosact.com).
### Known issues
- Running actions locally require a Github Token. You can generate one by following instructions on [Github Docs](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens). After generating a token you will need to pass it to `act` either through the command line using `-s GITHUB_TOKEN=` or by adding it to the `~/.config/act/actrc` file.
- You might get an error about missing or incompatible `warp-ubuntu-latest-x64-32x` platform. This can be mitigated by adding `-P warp-ubuntu-latest-x64-32x=ghcr.io/catthehacker/ubuntu:act-latest` on the command line when calling `act` or appending this flag to `~/.config/act/actrc`