TOOL Reference¶

Use eth_sendBundle when an orderflow provider or external PBS builder wants to submit a Flashbots-style bundle into TOOL. TOOL validates the signed transactions, executes the bundle against the current TOOL block state, creates a source commitment, and returns the commitment id as bundleHash. The response confirms only acceptance. Where the bundle and solutions on it go depends on callbackUrl and builders (table in The builders Field): without a callback the bundle itself is forwarded to its builders in the background; with a callback nothing is forwarded and the callback receives solutions. Builder failures are never reported. The bundle is gossiped, so callbacks come from whichever node built a solution, signed with that node's key: expect zero, one, or several per submission.

eth_sendRawTransaction takes the same path in miniature: the transaction is also wrapped into a bundle with all builders and no callback, so it is forwarded to all builders right away.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_sendBundle",
  "params": [
    {
      "txs": ["0x..."],
      "blockNumber": "0x...",
      "minTimestamp": 0,
      "maxTimestamp": 0,
      "revertingTxHashes": [],
      "callbackUrl": "https://source.example/tool-callback",
      "builders": ["titan"]
    }
  ]
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "bundleHash": "0x..."
  }
}

Common rejection cases (full list in Errors):

Use ofp_sendUnsignedBundle as step 1 of the quote flow, when the user must not sign until the outcome of a backrun is known. TOOL creates an unsigned commitment and gossips it; searchers build solutions on it, and the node that accepted this call POSTs each candidate to callbackUrl as a quote. Only that node holds the unsigned bodies, so the follow-up ofp_sendSignedBundle must go to the same node.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "ofp_sendUnsignedBundle",
  "params": [
    {
      "txs": [{
        "from": "0x1111111111111111111111111111111111111111",
        "to": "0x2222222222222222222222222222222222222222",
        "value": "0x2386f26fc10000",
        "gas": "0x5208",
        "maxFeePerGas": "0x77359400",
        "maxPriorityFeePerGas": "0x3b9aca00",
        "nonce": "0x0",
        "chainId": "0x0"
      }],
      "blockNumber": "0x0",
      "callbackUrl": "https://your-ofp-endpoint.example.com/tool-quote"
    }
  ]
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "bundleHash": "0x..."
  }
}

Rate limit: 100 requests per second.

Use ofp_sendSignedBundle as step 5 of the quote flow to finalize the chosen quote, on the same node as ofp_sendUnsignedBundle. TOOL re-executes the signed transactions with the solver's and compares the resulting state diff with the quoted one: any change of the outcome fails with signed bundle state diff mismatch; differences that leave the state untouched (a higher gas limit with the same gas used) are accepted. The signed bundle then always joins the pool and gossip, so relay merging can include it and searchers can build on it. If callbackUrl is set, TOOL sends the final callback (Callback Receiver Contract) before the RPC response, then forwards the bundle to the selected builders in the background.

If a transaction of the chosen candidate has not reached the node yet, the call waits up to 1 second for the missing transaction, or until the block is sealed if that comes first. A shorter client timeout ends the call first.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "ofp_sendSignedBundle",
  "params": [
    {
      "txs": ["0x02f8b0..."],
      "blockNumber": "0x0",
      "callbackUrl": "https://your-ofp-endpoint.example.com/tool-final",
      "builders": ["titan", "flashbots"],
      "unsignedCmtId": "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
    }
  ]
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "bundleHash": "0x..."
  }
}

Use tool_sendBundle when a TOOL searcher has built a native bundle from one or more base commitments and optional new signed transactions. The method creates the solution, stores it in the TOOL pool, gossips it, and starts its delivery in the background. It returns before delivery: the response does not say whether the solution was delivered, and delivery failures are only logged on the node. already known means the solution is already in the network; do not resubmit. The call is bounded by the node's RPC execution timeout, which covers preparation and execution but not delivery.

The solution's callback and builders are derived from its bases: without bases it gets all builders and no callback; with bases the builders are the intersection and the callback is kept only if every base has the same one, otherwise it becomes mixed-origin (see Callback and Builders of a Solution). Read callbackUrl and extBuilders in the returned Commitment to see where it goes. See Submitting Solutions.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tool_sendBundle",
  "params": [
    {
      "basedCommitments": ["0x..."],
      "newTxs": ["0x..."],
      "blockTime": 0,
      "blockParent": "0x...",
      "subslot": 0,
      "expirySubslot": 14
    }
  ]
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "id": "0x...",
    "blockTime": 0,
    "blockParent": "0x...",
    "subslot": 0,
    "expirySubslot": 14,
    "txsSize": 0,
    "execGasUsed": 0,
    "stateGasUsed": 0,
    "maxExecGasLimit": 0,
    "maxStateGasLimit": 0,
    "fees": "0",
    "accesses": {},
    "extBuilders": ["flashbots", "titan"],
    "stateDiff": { "accounts": {} }
  }
}

Common rejection cases (see Rejection Checks):

Use tool_simulateBundle to evaluate the same native ToolBundle shape used by tool_sendBundle. It runs the same preparation, including the merge rules and rejection checks, and returns the commitment without storing, gossiping, or delivering anything.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tool_simulateBundle",
  "params": [
    {
      "basedCommitments": ["0x..."],
      "newTxs": ["0x..."]
    }
  ]
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "id": "0x...",
    "blockTime": 0,
    "blockParent": "0x...",
    "subslot": 0,
    "expirySubslot": 14,
    "txsSize": 0,
    "execGasUsed": 0,
    "stateGasUsed": 0,
    "maxExecGasLimit": 0,
    "maxStateGasLimit": 0,
    "fees": "0",
    "accesses": {},
    "stateDiff": { "accounts": {} }
  }
}

Use tool_nextBlockParams to read the current block-building constraints before creating or sizing a native TOOL bundle.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tool_nextBlockParams",
  "params": [
    "0x...parentHash",
    0
  ]
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "reservedGas": 0,
    "reservedSize": 0,
    "proposerPreferences": {
      "blockSealOffsetMs": 0,
      "filterOFAC": false
    }
  }
}

Use tool_subscribe over WebSocket for live TOOL events. The initial result is a subscription id. Notifications use the standard JSON-RPC subscription shape.

{
  "jsonrpc": "2.0",
  "method": "tool_subscription",
  "params": {
    "subscription": "0x...",
    "result": {}
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tool_subscribe",
  "params": [
    "commitments",
    {
      "0x0000000000000000000000000000000000000000": true
    }
  ]
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tool_subscribe",
  "params": ["subslots"]
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tool_subscribe",
  "params": ["nextHeaders"]
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tool_subscribe",
  "params": ["buildSchedule"]
}

TOOL preserves standard Ethereum JSON-RPC method names for selected read paths. When the requested block is available in TOOL preconfirmed state, these methods read from that state. When TOOL state is not available for the selector or object, the implementation falls back to the normal Ethereum behavior.

Use tee_getAttestation when an integrator needs a fresh TEE attestation quote bound to a caller-provided nonce and the TLS certificate public key served by the node.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tee_getAttestation",
  "params": [
    {
      "userNonce": "00112233445566778899aabbccddeeff",
      "certScope": "network"
    }
  ]
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "evidenceBundle": {},
    "tlsCertFingerprint": "...",
    "challenge": "...",
    "sessionId": "...",
    "keyDelegation": "..."
  }
}

Verifier checklist (tlsCertPubKeyDER is the DER-encoded public key of the certificate observed during the TLS handshake):