op-rbuilder

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 setup

To run the op-rbuilder, run:

cargo run -p op-rbuilder --bin op-rbuilder --features flashblocks -- node \
    --chain /path/to/chain-config.json \
    --http \
    --authrpc.port 9551 \
    --authrpc.jwtsecret /path/to/jwt.hex

To build the op-rbuilder, run:

cargo build -p op-rbuilder --bin op-rbuilder --features optimism

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 which will expose reth metrics in addition to op-rbuilder metrics. op-rbuilder exposes on-chain metrics via reth execution extensions 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.

Integration Testing

op-rbuilder has an integration test framework that runs the builder against mock engine api payloads and ensures that the builder produces valid blocks.

To run the integration tests, run:

# Ensure you have op-reth installed in your path,
# you can download it with the command below and move it to a location in your path
./scripts/ci/download-op-reth.sh

# Generate a genesis file
cargo run -p op-rbuilder --bin tester -- genesis --output genesis.json

# Build the op-rbuilder binary
# To test flashblocks add flashblocks as a feature
cargo build -p op-rbuilder --bin op-rbuilder

# Run the integration tests
# To test flashblocks add flashblocks as a feature
cargo test --package op-rbuilder --lib --features integration -- integration::integration_test::tests

Local Devnet

1. Clone flashbots/builder-playground and start an OPStack chain.

git clone https://github.com/flashbots/builder-playground.git
cd builder-playground
go run main.go cook opstack --external-builder http://host.docker.internal:4444

2. Remove any existing reth chain db. The following are the default data directories:

• Linux: $XDG_DATA_HOME/reth/ or $HOME/.local/share/reth/
• Windows: {FOLDERID_RoamingAppData}/reth/
• macOS: $HOME/Library/Application Support/reth/

3. Run op-rbuilder in the rbuilder repo on port 4444:

cargo run -p op-rbuilder --bin op-rbuilder -- node \
    --chain $HOME/.playground/devnet/l2-genesis.json \
    --http --http.port 2222 \
    --authrpc.addr 0.0.0.0 --authrpc.port 4444 --authrpc.jwtsecret $HOME/.playground/devnet/jwtsecret \
    --port 30333 --disable-discovery \
    --metrics 127.0.0.1:9011 \
    --rollup.builder-secret-key ac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 \
    --trusted-peers enode://3479db4d9217fb5d7a8ed4d61ac36e120b05d36c2eefb795dc42ff2e971f251a2315f5649ea1833271e020b9adc98d5db9973c7ed92d6b2f1f2223088c3d852f@127.0.0.1:30304

4. Init contender:

git clone https://github.com/flashbots/contender
cd contender
cargo run -- setup ./scenarios/simple.toml http://localhost:2222

6. Run contender:

cargo run -- spam ./scenarios/simple.toml http://localhost:2222 --tpb 10 --duration 10

And you should start to see blocks being built and landed on-chain with contender transactions.

Builder playground

You can quickly spin up an op-stack devnet using builder-playground. The quickest workflow to get op-stack running against your local op-rbuilder instance is:

1. Check out the builder playground repo

git clone git@github.com:flashbots/builder-playground.git

2. In the builder-playgound spin up an l2 opstack setup specifying that it should use an external block builder:

go run main.go cook opstack --external-builder http://host.docker.internal:4444

3. Run rbuilder in playground mode:

cargo run --bin op-rbuilder -- node --builder.playground

You could also run it using:

just run-playground

This will automatically try to detect all settings and ports from the currently running playground. Sometimes you might need to clean up the builder-playground state between runs. This can be done using:

rm -rf ~/.local/share/reth
sudo rm -rf ~/.playground

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.

Known issues

• Running actions locally require a Github Token. You can generate one by following instructions on Github Docs. After generating a token you will need to pass it to act either through the command line using -s GITHUB_TOKEN=<your 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