TOOL Integration Overview¶

Shared Concepts¶

Common Flow¶

TOOL (in the Searcher Network/v0 stage) accepts private or pre-merged orderflow, converts valid submissions into Commitments, lets searchers build on the allowed Commitment view inside the TOOL network, and routes valid enriched bundles according to callback and block-production policy.

flowchart TB
  subgraph Sources["Source integrator boundary"]
    direction TB
    SourceClients["OFP and PBS builder clients<br/>private txs and bundles"]
    SourceAuth["Callback receiver<br/>verifies X-Flashbots-Signature"]
    Verifier["TEE verifier<br/>optional RA-TLS policy"]
  end

  subgraph ToolNetwork["TOOL network"]
    direction TB
    subgraph ToolTEE["TOOL node TEE environment"]
      direction TB
      Intake["Gateway and source intake<br/>eth_sendBundle / ofp_* / TOOL RPC"]
      Commitments["Commitment engine and feed<br/>origin tracking and timing"]
      Routing["Bundle API and routing policy<br/>simulate, submit, classify"]
      Native["Native block path<br/>subslot and relay delivery"]
      Intake -->|"form source commitments"| Commitments
      Commitments -->|"validated metadata"| Routing
      Routing -->|"accepted internal flow"| Native
    end

    subgraph SearcherTEE["Searcher context inside TOOL"]
      direction TB
      SearcherView["Allowed commitment view"]
      SearcherRuntime["Searcher / solver logic"]
      SearcherBundle["Native TOOL bundle<br/>source commitments + searcher txs"]
      SearcherView -->|"evaluate opportunities"| SearcherRuntime
      SearcherRuntime -->|"build and submit"| SearcherBundle
    end

    Commitments -->|"stream allowed commitments"| SearcherView
    SearcherBundle -->|"tool_simulateBundle / tool_sendBundle"| Routing
  end

  subgraph Delivery["Delivery contexts"]
    direction TB
    Callback["OFP callback<br/>solutions on its own flow"]
    Builders["External builders<br/>builders allow-list"]
    Relay["MEV-Boost relay path"]
    Validator["Validator"]
    Relay -->|"block proposal path"| Validator
  end

  SourceClients -->|"submit private txs / bundles"| Intake
  Routing -.->|"signed callback"| SourceAuth
  Verifier -.->|"verify attested endpoint"| Intake
  Routing -->|"same-callback solution"| Callback
  Routing -->|"intersection of builders"| Builders
  Native -->|"payload delivery"| Relay

  style Sources 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 SearcherTEE fill:#fff7ed,stroke:#a56812,stroke-width:2px
  style Delivery fill:#fff1f2,stroke:#b03a5b,stroke-width:2px

API Orientation¶

Different roles use different parts of the API surface. This overview names the relevant surfaces so each role can find the right integration path; Reference is the source of truth for schemas, examples, endpoint shapes, and method-level validation behavior.

Delivery Rules¶

Order flow reaches a node as a bundle or a plain transaction. The node turns it into a commitment: the transactions, their execution result and the block they target. Commitments live in the node's pool and are gossiped to all nodes. Searchers build solutions on top of them. Each commitment carries two delivery attributes: a callback and builders.

flowchart TB
  subgraph IN["Order flow"]
    A["eth_sendBundle"]
    B["eth_sendRawTransaction"]
    C["ofp_sendUnsignedBundle"]
    D["Mempool tx from peers"]
  end
  IN --> P[("Commitment pool + gossip")]
  S["Searchers: tool_sendBundle"] -->|"solutions on bases"| P
  P -->|"same callback on every base"| CB["OFP callback"]
  P -->|"intersection of builders"| BL["External builders"]
  P -->|"relay-only"| RM["Relay merging node"]
  RM --> RL["External relay"]

1. Builders are an allow-list. An empty list means "never send to external builders".
2. Defaults apply only where order flow enters. No callback and no builders: all builders. A callback and no builders: none. An explicit "builders": []: none.
3. A solution reaches only the builders that every base allows (intersection).
4. A callback sees only its own source's transactions. A solution keeps a callback only if all its bases have that same callback. Otherwise its callback becomes mixed-origin and it is never delivered to a callback.
5. A solution with no callback and no builders is relay-only. Relay merging nodes create it and hand it to the external relay; other nodes reject it. A solution on an unsigned (quote-flow) bundle can never be merged with another source.

6. Whether a new commitment is delivered right away depends on where it came from:

   Source	Delivered right away
   Mempool transaction relayed by peers	Nothing; only solutions on it are delivered
   OFP bundle with a callback	Nothing; the OFP receives solutions and decides itself
   OFP bundle without a callback (including eth_sendRawTransaction)	The bundle itself, to its builders
   Searcher solution, signed quote-flow bundle	To its callback and its builders

7. Delivery is best effort. A callback gets 5 seconds and is not retried; builder requests are asynchronous and their failures are only logged. Only ofp_sendSignedBundle waits for its callback and reports its error; everything else is delivered in the background. If raw transactions are missing, delivery waits for them until the block is sealed, and is dropped if a new block starts or the commitment leaves the pool.

Entry Points¶

Delivery by Participant¶

Pick your role to see only what applies to you: where your flow or solutions end up, and who can see them.

Terms used in every view:

• Relay merging only: no callback and no external builder can receive it. Relay merging nodes include it in the payload they submit to the external relay; other nodes reject it with commitment has no delivery target.
• Right away: sent as soon as the node accepts it, without waiting for a solution.
• Every delivery is best effort (5 s, no retry) and is signed with the FlashbotsKey of the node that built it.

flowchart TB
  Bundle["Your bundle"] --> HasCb{"callbackUrl?"}
  HasCb -->|"no"| Direct["Bundle to your<br/>builders, right away"]
  HasCb -->|"yes"| Held["Bundle not<br/>forwarded"]
  Direct --> Sol["Searchers build<br/>solutions on it"]
  Held --> Sol
  Sol --> Own{"Only your<br/>flow?"}
  Own -->|"yes"| Yours["Your callback<br/>+ your builders"]
  Own -->|"no"| Shared{"Builder every<br/>bundle allows?"}
  Shared -->|"yes"| Common["Those builders,<br/>no callback"]
  Shared -->|"no"| Relay["Relay merging<br/>only"]

flowchart TB
  Bundle["Your bundle"] --> Bases{"Any<br/>bases?"}
  Bases -->|"no"| TOB["All builders"]
  Bases -->|"yes"| Unsigned{"Quote-flow<br/>base?"}
  Unsigned -->|"yes"| Q{"First, and<br/>callbacks match?"}
  Q -->|"yes"| Quote["Quote<br/>to OFP"]
  Q -->|"no"| Rej["Rejected"]
  Unsigned -->|"no"| Same{"Callbacks<br/>match?"}
  Same -->|"yes"| Keep["Callback +<br/>common builders"]
  Same -->|"no"| Common["Common<br/>builders only"]

flowchart TB
  Now["Sent right away (if they list you)<br/>OFP bundles without a callback<br/>eth_sendRawTransaction<br/>Signed quote-flow bundles"] --> You["Your builder endpoint<br/>eth_sendBundle"]
  Later["Never sent themselves<br/>OFP bundles with a callback<br/>Mempool transactions"] -->|"solutions on them,<br/>if every base lists you"| You

Shared Trust Model¶

Authentication and TEE verification are separate concerns.

Public Endpoints¶

Nuconstruct-hosted TOOL endpoints are available for mainnet searcher-network testing, Hoodi RPC access, and Hoodi validator relay integration.

https://tool-0.tool.limo:8545
https://tool-1.tool.limo:8545

https://rpc-hoodi.nuconstruct.xyz/
wss://rpc-hoodi.nuconstruct.xyz/ws

https://0xa0f46566247ceb1f259a7189d5ac8bf2f0f07c135f081b0b5a9f226ef864bf6362c74306fcd02a87b7941f6feac57dc7@relay-hoodi.nuconstruct.xyz

Onboarding¶

Technical Reference¶

Use Reference for method schemas, field definitions, endpoint shapes, and error strings. Use Technical Architecture after the relevant integration path is clear for deeper node behavior, subslots, commitment internals, peer networking, and relay delivery.