External Builder Integration¶

Builder Role¶

In this integration, a PBS builder can act as a source of private or pre-merged orderflow and as a downstream receiver of enriched bundles.

A builder does not need direct access to TOOL's internal commitment network, native searcher feed, or subslot consensus to use this integration.

Builder-Facing Submission¶

External builders submit source bundles through eth_sendBundle. TOOL turns an accepted builder bundle into a source commitment that searchers can build around according to the allowed commitment view.

Callback Loop¶

sequenceDiagram
  autonumber
  participant Builder as PBS builder
  participant TOOL as TOOL source intake
  participant Searcher as Searcher inside TOOL
  participant Policy as TOOL routing policy
  participant Callback as Builder callback
  participant Native as TOOL path

  Builder->>TOOL: eth_sendBundle(builder bundle, callback optional)
  TOOL->>TOOL: Validate and create source commitment
  TOOL-->>Builder: bundleHash
  TOOL-->>Searcher: Allowed commitment view
  Searcher->>TOOL: Submit bundle built on source commitment
  TOOL->>Policy: Validate enriched commitment
  alt all bases carry the builder's callback
    Policy->>Callback: eth_sendBundle(source txs + searcher txs), signed by delivering node's FlashbotsKey
  else no callback on the bundle
    Policy->>Native: Deliver to the allowed builders only
  else mixed-origin (merged with another source)
    Policy->>Native: Never sent to a callback; only builders allowed by every base, or the external relay on relay merging nodes
  end

Callback Receiver¶

When a solution's bases all carry the builder's callback, TOOL POSTs it to the builder's receiver using the callback receiver contract, in the same eth_sendBundle format that goes to builders. The payload passes through an existing builder pipeline without TOOL-specific block-building logic. See Callback Endpoint for the full receiver requirements.

Bundle Atomicity and Size¶

TOOL treats each submitted builder bundle as an atomic base unit:

There is no separate product-level gas or byte cap for builder bundles in the first version beyond implementation and resource constraints. If a subslot-sized bundle is accepted, TOOL searchers compete around that corresponding commitment.

Builders can choose bundle granularity. Smaller opportunity-sized bundles can give TOOL searchers more room to add value, while larger bundles may be simpler for existing builder pipelines.

Revenue Attribution¶

TOOL attributes revenue to the bundle originator it sees: the source whose commitment was included.

If an OFP sends flow to a PBS builder and the builder merges that flow into a larger bundle before submitting it to TOOL, the builder is the visible originator for that commitment unless a finer attribution model is available.

Authentication, TEE Verification, and Transport¶

Send an X-Flashbots-Signature header with each request to a TOOL node, as described in Conventions.

Callback participation is optional; a builder may submit flow without asking TOOL to return solutions. Callbacks are signed by the delivering TOOL node's FlashbotsKey; verify X-Flashbots-Signature against the TOOL signing addresses you trust as described in Callback Endpoint.

TEE verification is optional from the builder's perspective. Builders that require end-to-end verification can verify TOOL attestation before sending private flow. The stronger private-flow setup is RA-TLS, where the builder verifies attestation and sends bundles over a TLS connection bound to the attested service.

Later Delivery Paths¶

The callback path can coexist with TOOL-native block delivery. TOOL can both return same-origin solutions to a builder's callback and deliver to the external builders allowed by the builders field or, on relay merging nodes, to the external relay. See Delivery Rules.

flowchart TB
  subgraph ToolNetwork["TOOL network"]
    direction TB
    Commitments["Accepted TOOL commitments"]
    Finalization["TOOL finalization and routing"]
    Commitments -->|"subslot and block policy"| Finalization
  end

  subgraph CallbackDelivery["External builder callback path"]
    direction TB
    CallbackPath["Enriched bundle callback"]
    BuilderPipeline["Builder pipeline"]
    BuilderRelay["Builder / relay path"]
    CallbackPath -->|"eth_sendBundle payload"| BuilderPipeline
    BuilderPipeline -->|"existing downstream delivery"| BuilderRelay
  end

  subgraph NativeDelivery["TOOL-native delivery path"]
    direction TB
    RelayPath["TOOL relay path"]
    MEVBoost["MEV-Boost relay"]
    Validator["Validator / beacon node"]
    RelayPath -->|"payload delivery"| MEVBoost
    MEVBoost -->|"block proposal path"| Validator
  end

  Finalization -->|"same-origin solutions"| CallbackPath
  Finalization -->|"native block production"| RelayPath

  style ToolNetwork fill:#edf7f5,stroke:#0f8b6f,stroke-width:2px
  style CallbackDelivery fill:#f8fafc,stroke:#64748b,stroke-width:2px
  style NativeDelivery fill:#fff1f2,stroke:#b03a5b,stroke-width:2px

Failure Modes¶

See Errors and Delivery Rules.