Searcher Integration¶

Searcher Position In The Architecture¶

Searchers participate inside the TOOL network. They are not source integrators on the same integration plane as OFPs or external builders. The source side submits private flow; TOOL turns valid source flow into commitments; searchers consume the allowed commitment view and submit native TOOL bundles back to TOOL.

flowchart TB
  subgraph SourceSide["External source side"]
    direction TB
    OFP["OFP"]
    Builder["External PBS builder"]
    SourceFlow["Private source orderflow"]
    OFP --> SourceFlow
    Builder --> SourceFlow
  end

  subgraph ToolNetwork["TOOL network"]
    direction TB
    subgraph ToolTEE["TOOL node TEE environment"]
      direction TB
      Intake["Source intake"]
      CommitmentFeed["Commitment feed<br/>policy-controlled view"]
      Validation["Simulation and validation"]
      Routing["Callback and native routing"]
      Intake -->|"create source commitment"| CommitmentFeed
      Validation -->|"accepted enriched commitment"| Routing
    end

    subgraph SearcherContext["Searcher context"]
      direction TB
      Strategy["Searcher / solver logic"]
      Bundle["Native TOOL bundle<br/>source commitments + searcher txs"]
      CommitmentFeed -->|"allowed commitment metadata"| Strategy
      Strategy -->|"construct opportunity"| Bundle
      Bundle -->|"tool_simulateBundle / tool_sendBundle"| Validation
    end
  end

  SourceFlow -->|"eth_sendBundle or source path"| Intake

  style SourceSide fill:#f8fafc,stroke:#64748b,stroke-width:2px
  style ToolNetwork fill:#edf7f5,stroke:#0f8b6f,stroke-width:2px
  style ToolTEE fill:#eef2ff,stroke:#315fbe,stroke-width:2px
  style SearcherContext fill:#fff7ed,stroke:#a56812,stroke-width:2px

Searcher Flow¶

sequenceDiagram
  autonumber
  participant Source as OFP / builder
  participant TOOL as TOOL
  participant Searcher as Searcher
  participant Callback as Source callback
  participant Native as TOOL block path

  Source->>TOOL: Submit source orderflow
  TOOL->>TOOL: Validate and create source commitment
  TOOL-->>Searcher: Commitment event or allowed view
  Searcher->>TOOL: tool_simulateBundle(native bundle)
  Searcher->>TOOL: tool_sendBundle(enriched bundle)
  TOOL->>TOOL: Validate enriched bundle
  alt same-origin callback-safe
    TOOL->>Callback: Return source txs + searcher txs
  else not callback-safe
    TOOL->>Native: Keep commitment inside TOOL block path
  end

Searcher API Workflow¶

Searcher integrations usually follow the same API sequence: observe the allowed commitment view, size the opportunity against the current block, simulate when latency allows, then submit before the relevant subslot deadline.

The native bundle request uses the ToolBundle schema. A typical searcher bundle builds on a source commitment and adds the searcher's backrun or other signed transactions.

Commitment View¶

The commitment view is policy-controlled. Depending on deployment and access level, a commitment may expose block parent, block time, subslot and expiry metadata, gas and fee metrics, touched accounts or storage-access metadata, transaction hashes, or redacted execution metadata needed to determine whether a strategy can safely build on the commitment.

Raw signed transactions from another private source should not be assumed to be visible. Commitment metadata may be redacted or filtered when it would reveal private orderflow or strategy.

Callback Safety Rule¶

Searcher bundles may improve blocks internally even when they combine multiple source commitments. External callback exposure is stricter.

flowchart TB
  subgraph SearcherContext["Searcher bundle validation"]
    direction TB
    Bundle["Searcher bundle"]
    Based{"Based on one private source?"}
    Direct{"Directly extends that source?"}
    Bundle -->|"inspect base commitments"| Based
    Based -->|"yes"| Direct
  end

  subgraph PolicyContext["TOOL routing policy"]
    direction TB
    Policy{"Source callback policy allows?"}
    Callback["Eligible for same-origin callback"]
    Internal["Native TOOL path only"]
    Direct -->|"yes"| Policy
    Based -->|"no"| Internal
    Direct -->|"no"| Internal
    Policy -->|"yes"| Callback
    Policy -->|"no"| Internal
  end

  style SearcherContext fill:#fff7ed,stroke:#a56812,stroke-width:2px
  style PolicyContext fill:#eef2ff,stroke:#315fbe,stroke-width:2px

Simulation and Submission Workflow¶

Searchers should expect low-latency constraints. Bundle size, simulation cost, and request rate can affect whether a strategy lands before the active deadline.

Authentication and TEE Verification¶

Searcher authentication and access policy may vary by deployment. Searchers should expect TOOL API access to be authenticated before receiving commitment data or submitting bundles.

TEE verification is optional from the integrator's perspective unless a deployment requires it. Searchers that require end-to-end assurances can verify TOOL attestation or RA-TLS before consuming commitment data or sending strategy transactions.

Failure Modes¶