Network, node, and API design

Technical Architecture¶

TOOL is implemented as a TEE-backed, peer-to-peer extension of the Ethereum block-building pipeline. It introduces commitments, 1-second subslots, TOOL-specific RPC and subscription surfaces, and an in-process MEV-Boost-compatible relay path while preserving Ethereum L1 settlement.

Integration Overview Reference Introduction

Architecture Principles¶

TEE-verifiable privacy¶

Sensitive orderflow is processed by code paths that can be verified through TEE attestation and, where required, RA-TLS.

Subslot feedback¶

Each Ethereum slot is divided into 1-second subslots, giving the network an intermediate execution and ordering cadence.

Distributed building¶

Commitments and subslots are propagated over a TOOL-specific peer network instead of being handled by a single off-chain builder.

Ethereum compatibility¶

TOOL keeps familiar JSON-RPC, bundle, and MEV-Boost delivery surfaces where they are useful for adoption.

Core Concepts¶

Concept	Technical role	Why it matters
Bundle	A request submitted to TOOL containing new signed transactions and, for native TOOL searcher flow, optional base commitments.	This is the main unit submitted by sources and searchers.
Commitment	The pre-execution result produced from a bundle. It includes execution metadata such as gas, fees, access lists, state diff, receipts, and timing constraints.	Commitments give searchers and block production a structured object to build around without exposing more private data than policy allows.
Subslot	A subdivision of an Ethereum slot (of 1 second duration in the current implementation). It holds an ordered set of non-conflicting commitments.	Subslots create the intermediate execution cadence that makes earlier feedback possible.
Access list and state diff	The read/write footprint and state changes created during pre-execution.	TOOL uses these to detect conflicts and merge compatible commitments.
TOOL pool	Per-block in-memory storage for pending commitments, known transactions, accepted receipts, and conflicts.	The pool resets with the block lifecycle and avoids adding separate persistent TOOL storage beyond the normal chain database.

System Context¶

flowchart TB
  subgraph External["External systems"]
    direction TB
    Sources["Wallets, apps, OFPs,<br/>external PBS builders"]
    Verifiers["TEE verifiers<br/>RA-TLS or attestation policy"]
    Validators["Validators / MEV-Boost clients"]
  end

  subgraph ToolNetwork["TOOL network"]
    direction TB
    subgraph ToolNode["TOOL node TEE environment"]
      direction TB
      Gateway["Gateway and RPC surface<br/>eth_sendBundle, TOOL RPC, eth overrides"]
      Engine["TOOL engine<br/>commitments, state diffs, access lists"]
      Pool["Per-block pool<br/>pending commitments, known txs, receipts"]
      Subslots["Subslot assembly<br/>1-second cadence, conflict checks"]
      Relay["In-process relay<br/>builder API and signed bids"]
      Gateway -->|"validated source flow"| Engine
      Engine -->|"commitment objects"| Pool
      Pool -->|"non-conflicting selection"| Subslots
      Subslots -->|"progressive payload updates"| Relay
    end

    subgraph SearcherPod["Searcher execution context inside TOOL"]
      direction TB
      Feed["Allowed commitment feed"]
      Strategy["Searcher / solver logic"]
      NativeBundle["Native TOOL bundle<br/>source commitments + searcher txs"]
      Feed -->|"strategy input"| Strategy
      Strategy -->|"simulate and submit"| NativeBundle
    end

    P2P["TOOL devp2p protocol<br/>commitments, subslots, validator registrations"]
    Engine -->|"publish allowed view"| Feed
    NativeBundle -->|"tool_sendBundle"| Engine
    Engine <-->|"gossip and sync"| P2P
  end

  subgraph Ethereum["Ethereum and delivery"]
    direction TB
    BuilderAPI["MEV-Boost builder API<br/>status, validators, header, payload"]
    Beacon["Consensus layer / beacon node"]
    L1["Ethereum L1 settlement"]
    BuilderAPI -->|"builder bid and payload reveal"| Beacon
    Beacon -->|"proposed block"| L1
  end

  Sources -->|"private txs or bundles"| Gateway
  Verifiers -.->|"verify endpoint before sensitive flow"| Gateway
  Validators -->|"register / request bids"| BuilderAPI
  Relay -->|"serve builder API"| BuilderAPI

  style External fill:#f8fafc,stroke:#64748b,stroke-width:2px
  style ToolNetwork fill:#edf7f5,stroke:#0f8b6f,stroke-width:2px
  style ToolNode fill:#eef2ff,stroke:#315fbe,stroke-width:2px
  style SearcherPod fill:#fff7ed,stroke:#a56812,stroke-width:2px
  style Ethereum fill:#fff1f2,stroke:#b03a5b,stroke-width:2px

Searchers are part of the TOOL network plane. They consume an allowed commitment view and submit native TOOL bundles back into the TOOL engine; they are not equivalent to off-chain source integrators that provide private orderflow from outside the network.

Runtime Lifecycle¶

sequenceDiagram
  autonumber
  participant Source as Source integrator
  participant RPC as TOOL RPC gateway
  participant Engine as TOOL engine
  participant Searcher as Searcher context
  participant P2P as TOOL peers
  participant Relay as In-process relay
  participant Validator as Validator / MEV-Boost
  participant L1 as Ethereum L1

  Source->>RPC: Submit private txs or bundle
  RPC->>Engine: Validate and process source flow
  Engine->>Engine: Create commitment with execution metadata
  Engine-->>Searcher: Publish allowed commitment view
  Engine-->>P2P: Gossip commitment
  Searcher->>Engine: Simulate and submit native TOOL bundle
  Engine->>Engine: Validate enriched commitment and conflicts
  loop Every subslot
    Engine->>Engine: Assemble non-conflicting commitments
    Engine-->>P2P: Broadcast accepted subslot
    Engine-->>Relay: Update in-progress payload
  end
  Validator->>Relay: Request builder header / payload
  Relay-->>Validator: Signed bid and payload reveal
  Validator->>L1: Propose block

Node Decomposition¶

flowchart TB
  subgraph Node["tool-node process"]
    direction TB
    Eth["eth/<br/>Ethereum service and TOOL handler"]
    InternalAPI["internal/ethapi<br/>TOOL RPC overrides"]
    ToolPkg["tool/<br/>commitment and subslot engine"]
    Miner["miner/<br/>TOOL-aware payload assembly"]
    Relay["relay/<br/>in-process MEV-Boost relay"]
    ToolProto["eth/protocols/tool<br/>devp2p protocol"]
    NodeGov["eth/nodegov<br/>leader set and TEE verifier"]
    Tee["tee/<br/>attestation and RA-TLS service"]

    InternalAPI -->|"SendBundle, preconfirmed reads"| Eth
    Eth -->|"lifecycle and backend calls"| ToolPkg
    ToolPkg -->|"subslot batches"| Miner
    Miner -->|"EnvelopeElapsed updates"| Relay
    Eth -->|"commitments and subslots"| ToolProto
    ToolProto -->|"peer eligibility"| NodeGov
    Tee -->|"quotes and TLS binding"| NodeGov
    Tee -->|"tee_getAttestation"| InternalAPI
  end

  subgraph ExternalRuntime["External runtime dependencies"]
    direction TB
    CL["Consensus layer"]
    Beacon["Beacon HTTP API"]
    Peer["TEE-attested TOOL peer"]
    Contracts["On-chain verifier / leader-set contracts"]
  end

  CL -->|"Engine API"| Eth
  Beacon -->|"head and payload events"| Relay
  ToolProto <-->|"tool/1 messages"| Peer
  NodeGov -->|"staticcall verification"| Contracts

  style Node fill:#edf7f5,stroke:#0f8b6f,stroke-width:2px
  style ExternalRuntime fill:#f8fafc,stroke:#64748b,stroke-width:2px

The current node is a go-ethereum fork with TOOL-specific extensions concentrated in companion files and packages. The key implementation split is:

Subsystem	Responsibility
`tool/`	Commitment creation, simulation, subslot assembly, conflict detection, preconfirmed state queries, and event feeds.
`internal/ethapi`	TOOL-aware overrides for `eth_call`, `eth_getTransactionCount`, `eth_getTransactionReceipt`, `eth_getBlockByHash`, and bundle submission.
`eth/protocols/tool`	TOOL devp2p protocol for commitment, subslot, transaction, and validator-registration messages.
`relay/`	In-process MEV-Boost builder API, validator registration, signed bid construction, and payload reveal.
`tee/`	Quote generation and verification, TLS session binding, and `tee_getAttestation`.
`ethclient/toolclient`	Typed client subscriptions for `nextHeaders`, `subslots`, and `commitments`.

Architectural Interface Map¶

TOOL exposes several interfaces because different participants sit on different trust and timing boundaries. This page describes where those interfaces fit in the node architecture; Reference defines exact method schemas, endpoint shapes, and compatibility behavior.

Interface area	Architectural owner	Role in the system
Source and builder ingress	RPC gateway and TOOL engine	Converts external private flow into source commitments.
Searcher RPC and subscriptions	TOOL engine, pool, and event feeds	Lets searchers observe allowed commitment data, simulate bundles, and submit native TOOL commitments.
Preconfirmed Ethereum reads	TOOL-aware Ethereum API overrides	Preserves standard Ethereum method names while reading TOOL preconfirmed state when available.
TEE attestation	TEE service and node governance verifier	Lets integrators verify the endpoint before sending sensitive flow.
MEV-Boost builder HTTP	In-process relay	Presents TOOL-built payloads through validator-compatible builder APIs.

Commitment and Subslot Processing¶

TOOL simulation runs against a state snapshot. When a bundle is processed, the executor captures its access footprint and state diff, then reverts the snapshot. When a subslot is accepted, TOOL applies the selected commitments to the working state so the next subslot starts from the accumulated result.

flowchart TB
  subgraph Simulation["Simulation path"]
    direction TB
    Bundle["Bundle<br/>source or searcher"]
    Snapshot["StateDB snapshot"]
    Execute["EVM execution"]
    Accesses["Accesses<br/>read/write footprint"]
    StateDiff["StateDiff<br/>execution result"]
    Commitment["Commitment"]
    Bundle -->|"execute against snapshot"| Snapshot
    Snapshot --> Execute
    Execute -->|"capture"| Accesses
    Execute -->|"capture"| StateDiff
    Accesses --> Commitment
    StateDiff --> Commitment
  end

  subgraph Assembly["Subslot assembly path"]
    direction TB
    Pending["Pending commitments"]
    Conflict["Conflict detection<br/>access-list intersection"]
    Limits["Gas, blob, and size limits"]
    Subslot["Accepted subslot"]
    Apply["Apply state diff<br/>advance working state"]
    Pending -->|"rank and evaluate"| Conflict
    Limits -->|"capacity guard"| Conflict
    Conflict -->|"select compatible commitments"| Subslot
    Subslot --> Apply
  end

  Commitment -->|"add to pool"| Pending

  style Simulation fill:#eef2ff,stroke:#315fbe,stroke-width:2px
  style Assembly fill:#edf7f5,stroke:#0f8b6f,stroke-width:2px

Trust and Security Boundaries¶

Boundary	Mechanism	Practical meaning
Private-flow processing	TEE attestation and optional RA-TLS	Integrators can verify the endpoint before sending sensitive orderflow.
Peer eligibility	TOOL-specific peer set, TEE verification, and leader-set policy	TOOL data propagation can be limited to eligible, attested participants.
Callback safety	Same-origin routing policy	Private flow from one source is not returned to a different source through the callback path.
Block settlement	Ethereum L1 consensus	TOOL can provide earlier execution feedback, but final settlement remains on Ethereum.
Relay delivery	MEV-Boost builder API and BLS-signed bids	Validators can consume TOOL-built payloads through familiar infrastructure.

Method reference¶

Reference defines request and response schemas for the documented RPC methods, subscriptions, callbacks, and relay endpoints.

Common integration¶

Integration Overview explains shared flow, routing policy, and compatibility boundaries.

Source integrations¶

Orderflow Providers and External Builders cover private-flow ingress and callbacks.

Searcher integration¶

Searcher Integration covers the commitment feed, native TOOL bundles, simulation, and submission workflow.