Source integration branch

Orderflow Provider Integration¶

This guide is for orderflow providers that want to route private transactions or bundles into TOOL and optionally receive enriched bundles back through a callback.

Integration Overview Reference Searcher Integration

Value Proposition¶

Orderflow providers can send private orderflow into TOOL, keep callback participation optional, and let TOOL searchers compete to add value around that flow. When a callback is enabled and the enriched bundle is same-origin safe, TOOL can return the enriched bundle to the source without exposing unrelated private flow.

OFP Role¶

An OFP may integrate directly with TOOL or route through an external PBS builder. Direct integration gives TOOL a clearer source commitment and attribution boundary. Routing through a builder can be operationally simpler when the builder already aggregates the OFP's flow.

OFP capability	Integration purpose
Private transactions	Source flow for TOOL commitments.
Atomic bundles	Pre-arranged execution intent that TOOL should preserve.
Source authentication	Required for callback eligibility.
Optional callback endpoint	Receives enriched bundles when policy allows.
Attribution metadata	Supports finer source accounting once final source-identity semantics are defined.

Submission Flow¶

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

  OFP->>TOOL: eth_sendBundle(source bundle, callback optional)
  TOOL->>TOOL: Validate and create source commitment
  TOOL-->>Searcher: Allowed commitment view
  Searcher->>TOOL: Submit bundle built on source commitment
  TOOL->>Policy: Validate enriched commitment
  alt same-origin callback-safe
    Policy->>Callback: Return source txs + searcher txs
  else no callback or not callback-safe
    Policy->>Native: Keep commitment in TOOL-native path
  end

Source Submission¶

OFPs submit private transactions or atomic bundles through eth_sendBundle. The same SendBundleArgs shape supports callback-enabled and non-callback source flow, so an OFP can start with one-way ingress and add callback participation later.

When callbacks are enabled, the OFP must operate a receiver that accepts TOOL's callback receiver contract. Callback participation is optional; source flow can still enter the native TOOL path without a callback endpoint.

Callback Behavior¶

Condition	Behavior
Callback not configured	Flow may still enter the native TOOL path, but no enriched bundle is returned.
Source authentication succeeds	TOOL may use the registered callback policy for same-origin payloads.
Enriched bundle is same-origin safe	TOOL may return the source transactions plus direct searcher transactions.
Enriched bundle contains mixed-origin private flow	No same-origin callback is sent in the initial model.
Callback fails	Failed callbacks are not rerouted to alternate destinations.

Attribution¶

TOOL attributes inclusion to the source commitment it sees. If an OFP sends flow directly to TOOL, the OFP can be the visible source. If an OFP sends flow to a builder and the builder submits a merged bundle to TOOL, the builder is the visible source for that merged commitment unless a later attribution model is agreed.

Authentication and TEE Verification¶

Callback-enabled sources should expect Flashbots-style authentication. TEE verification is optional from the integrator's side: OFPs that require end-to-end privacy assurance can verify TOOL attestation or RA-TLS before sending private flow.

Privacy-sensitive deployments

Use attestation verification before sending private flow when the integration requires proof that traffic is terminating inside the expected TOOL environment. Use RA-TLS when the transport itself must be bound to that attested service.

Failure Modes¶

Failure mode	Behavior
Callback is not configured	The flow may still enter the native TOOL path, but no enriched bundle is returned.
Callback authentication fails	No callback is sent.
Enriched commitment contains mixed-origin private flow	No same-origin callback is sent in the initial model.
Flow is routed through a builder	TOOL attributes the commitment to the builder unless a finer attribution model is available.