rbuilder Documentation

The test-relay crate provides a dummy MEV-boost relay implementation. It allows block builders to test their workflows without submitting to a production MEV-boost relay.

To use test-relay, you must provide:

• A real MEV-boost relay URL
• A connection to a consensus layer node
• (Optional) A validation endpoint to validate blocks

It also exposes metrics, such as estimated slot auction winners among builders who submit to this relay.

The Parallel Builder is a block building algorithm designed to run key building components in parallel to enable more sophisticated bundle merging.

Its primary mechanism is identifying groups of conflicting orders and resolving them independently and in parallel. This allows the system to pipeline the stages of orderflow intake, conflict resolution, and final block construction.

The rbuilder can be configured to use a watchdog to ensure the builder is actively processing slots. If watchdog_timeout is set in the BaseConfig, a watchdog thread is spawned. The builder must send a message for every slot it starts building; otherwise, the watchdog will trigger a process kill to prevent the service from hanging in an unhealthy state.

Use create_start_slot_watchdog to initialize this mechanism using a BaseConfig and a CancellationToken.

pub fn create_start_slot_watchdog(
    config: &BaseConfig,
    cancel: CancellationToken,
) -> std::io::Result<Option<flume::Sender<()>>>

Publishers are defined in the configuration file using the [[publishers]] array syntax. Each publisher requires a type and a unique name. The type determines which specific parameters are required for that publisher instance.

[[publishers]]
type = "relay-headers"
name = "relay-headers-1"

rbuilder supports multiple building algorithms, and each algorithm can be instantiated multiple times with its own unique set of parameters. Each algorithm instance must include a name and an algo type.

Supported algorithms:

• ordering-builder: Uses the OrderingBuildingAlgorithm.
• parallel-builder: (Experimental) Uses the ParallelBuilder.

To use environment variables for any parameter, prefix the value with env: followed by the variable name (e.g., env:MY_VAR_NAME).

[[algorithms]]
name = "my-ordering-algo"
algo = "ordering-builder"
discard_txs = true
sorting = "mev-gas-price"
failed_order_retries = 3
drop_failed_orders = false

In the LiveBuilder dataflow, once blocks are filled with orders, they must be converted into bids. This involves two main steps:

1. Bidding Decision: Deciding how much to bid for a block. Every block has a true block value (the MEV generated by the block).
   • Bidding 0 aims for maximum profit (the full true block value).
   • Bidding the true block value results in zero profit.
   • Bidding above the true block value results in a loss (subsidizing the block).
2. Sealing: Inserting the final payout transaction for the validator and computing the root hash.

To implement this, the rbuilder example uses BlockSealingBidderFactory as the UnfinishedBlockBuildingSinkFactory.

Because order cancellations can decrease the true block value of a block currently being built by an algorithm, rbuilder does not simply bid every block it receives. Instead, it selects the best available block across all running building algorithms.

This is handled by the UnfinishedBlockBuildingSinkMuxer. It acts as an UnfinishedBlockBuildingSink that receives all generated blocks and forwards only the one with the highest true block value to the next stage of the pipeline.

Example Scenario: If Algorithm A produces a block with value 4, but then an order is cancelled and its value drops to 2, the Muxer will switch to using a block from Algorithm B that has a value of 3.

The LiveBuilder struct is the central orchestrator of rbuilder. To instantiate it, you must provide three core components:

1. blocks_source: An implementation of the SlotSource trait that provides the source of slots to build. This allows rbuilder to work in different contexts, such as L1 (consensus client slots) or L2 (sequencer slots).
2. builders: A vector of objects implementing the BlockBuildingAlgorithm trait. Each builder takes a base block state and a stream of simulated orders to continuously generate and optimize blocks for maximum value.
3. sink_factory: A factory implementing UnfinishedBlockBuildingSinkFactory used to create the destination for built blocks. This abstraction handles different environments like L1 (requiring bidding), L2 (no bidding), or testing environments.