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 callback authenticated and same-origin safe
    Policy->>Callback: eth_sendBundle(source txs + searcher txs)
  else no callback or unsafe payload
    Policy->>Native: Keep commitment inside TOOL path
  end

Callback Receiver¶

When a callback is configured and routing policy allows it, TOOL returns an enriched bundle to the builder's receiver using the callback receiver contract. The returned payload is intended to pass through an existing builder pipeline without requiring TOOL-specific block-building logic.

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¶

Flashbots-style authentication is required for callback-enabled sources. Callback participation is optional; a builder may submit flow without asking TOOL to return enriched bundles.

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. In later production setups, TOOL can both return enriched bundles to builders and submit final blocks through its own relay path.

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 callback-safe"| 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¶