Method and schema reference

TOOL Reference¶

This page defines the public methods and endpoints mentioned in the integration and architecture docs. It focuses on the current TOOL-facing surface: source bundle ingress, native searcher bundles, subscriptions, preconfirmed state reads, TEE attestation, callbacks, and MEV-Boost-compatible relay endpoints.

Integration Overview Searcher Integration

Method Index¶

JSON-RPC eth_sendBundle Source and builder bundle ingress.

JSON-RPC tool_sendBundle Native TOOL bundle submission.

JSON-RPC tool_simulateBundle Native TOOL bundle simulation.

JSON-RPC tool_nextBlockParams Current block-building reserves and seal offset.

WebSocket tool_subscribe Commitments, subslots, next headers, and timing events.

JSON-RPC Preconfirmed eth_* TOOL-aware state, nonce, receipt, and block reads.

JSON-RPC tee_getAttestation TEE quote bound to nonce and TLS certificate.

HTTP Builder API MEV-Boost status, validator, header, and payload endpoints.

Conventions¶

Convention	Meaning
JSON-RPC envelope	All RPC examples use `{"jsonrpc":"2.0","id":1,"method":"...","params":[...]}`.
Hash	`0x`-prefixed 32-byte value. Used for commitment ids, transaction hashes, block hashes, storage slots, and parent hashes.
Address	`0x`-prefixed 20-byte Ethereum address.
Signed transaction	`0x`-prefixed Ethereum transaction bytes, not a transaction object.
Block number	Ethereum JSON-RPC block number or tag. For `eth_sendBundle`, TOOL currently accepts `0x0`, `pending`, `latest`, or the current next block number.
Time	Block and timestamp fields are Unix seconds unless otherwise noted.
Operation mask	Access masks use `1` for read, `2` for write, and `3` for read/write.
WebSocket subscriptions	Use `tool_subscribe` to create a subscription and `tool_unsubscribe` with the returned subscription id to cancel it.

Current compatibility boundary

Blob transactions are rejected on TOOL bundle paths. Flashbots-style replacementUuid and builders fields are recognized by the request shape but are not product-supported; clients should omit them.

Shared Schemas¶

Schema: SendBundleArgs

SendBundleArgs is the request object for inbound eth_sendBundle and for callback payloads sent by TOOL.

{
  "txs": ["0x..."],
  "blockNumber": "0x...",
  "minTimestamp": 0,
  "maxTimestamp": 0,
  "revertingTxHashes": ["0x..."],
  "callbackUrl": "https://source.example/tool-callback"
}

Field	Type	Required	Description
`txs`	`string[]`	Yes	Signed Ethereum transactions encoded as `0x` bytes. Must be non-empty. Blob transactions are rejected.
`blockNumber`	`quantity \\| tag`	Yes	Target block. Current TOOL validation accepts `0x0`, `pending`, `latest`, or the current next block number.
`minTimestamp`	`uint64`	No	Minimum acceptable TOOL block timestamp. The bundle is rejected if this is greater than the current TOOL block time.
`maxTimestamp`	`uint64`	No	Maximum acceptable TOOL block timestamp. The bundle is rejected if this is less than the current TOOL block time.
`revertingTxHashes`	`hash[]`	No	Transaction hashes from `txs` that may revert without invalidating the bundle. Every listed hash must be present in `txs`.
`callbackUrl`	`string`	No	Source callback endpoint. Must be an `http` or `https` URL with a host and no more than 512 characters.
`replacementUuid`	`uuid`	No	Flashbots-style field. Not currently product-supported.
`builders`	`string[]`	No	Flashbots-style field. Not currently product-supported.

Schema: ToolBundle

ToolBundle is the native request object for tool_sendBundle and tool_simulateBundle.

{
  "basedCommitments": ["0x..."],
  "blockTime": 0,
  "blockParent": "0x...",
  "subslot": 0,
  "expirySubslot": 14,
  "newTxs": ["0x..."]
}

Field	Type	Required	Description
`basedCommitments`	`hash[]`	No	Existing commitment ids this bundle builds on. At least one `basedCommitments` entry or one `newTxs` entry is required.
`blockTime`	`uint64`	No	Target block timestamp. If omitted, TOOL uses the current block time. If provided, it must match the current TOOL block time.
`blockParent`	`hash`	No	Target parent block hash. If omitted, TOOL uses the current parent. If provided, it must match the current TOOL parent.
`subslot`	`uint8`	No	First subslot where the resulting commitment may be accepted. Defaults to the current next subslot.
`expirySubslot`	`uint8`	No	Last subslot where the resulting commitment may be accepted. Must not be earlier than the current next subslot.
`newTxs`	`string[]`	No	New signed transactions encoded as `0x` bytes. Blob transactions are rejected.

Schema: Commitment

Commitment is the result for native bundle submission/simulation and the notification payload for tool_subscribe commitments.

{
  "id": "0x...",
  "blockTime": 0,
  "blockParent": "0x...",
  "subslot": 0,
  "expirySubslot": 14,
  "txsSize": 0,
  "gasUsed": 0,
  "maxGasLimit": 0,
  "fees": "0",
  "accesses": {},
  "callbackUrl": "https://source.example/tool-callback",
  "logs": [],
  "stateDiff": { "accounts": {} }
}

Field	Type	Description
`id`	`hash`	Commitment identifier. For `eth_sendBundle`, this is returned as `bundleHash`.
`blockTime`	`uint64`	Block timestamp the commitment targets.
`blockParent`	`hash`	Parent block hash the commitment targets.
`dirty`	`boolean`	Present only when a commitment needs reprocessing.
`subslot`	`uint8`	First acceptable subslot.
`expirySubslot`	`uint8`	Last acceptable subslot.
`txsSize`	`uint64`	Total encoded transaction size in bytes.
`gasUsed`	`uint64`	Gas consumed by executing the commitment.
`maxGasLimit`	`uint64`	Largest remaining block gas requirement for inclusion.
`fees`	`integer`	Total fees paid by the commitment transactions.
`accesses`	`Accesses`	Account and storage read/write footprint.
`callbackUrl`	`string`	Same-origin callback URL propagated from a source bundle, when present.
`logs`	`Log[]`	Ethereum logs generated by execution. May be omitted when trimmed.
`stateDiff`	`StateDiff` `\\| null`	State changes generated by execution. May be `null` when trimmed.

Schema: Accesses and StateDiff

Accesses is encoded as an object keyed by account address.

{
  "0x0000000000000000000000000000000000000000": {
    "balance": 1,
    "nonce": 2,
    "code": 0,
    "storage": {
      "0x...slot": 3
    }
  }
}

Field	Type	Description
`balance`	`uint8`	Balance access mask. `1` read, `2` write, `3` read/write.
`nonce`	`uint8`	Nonce access mask.
`code`	`uint8`	Code access mask.
`storage`	`object<hash,uint8>`	Storage slot access masks keyed by slot hash.

StateDiff is encoded as an object keyed by account address under accounts.

{
  "accounts": {
    "0x0000000000000000000000000000000000000000": {
      "balance": "0",
      "nonce": 1,
      "code": "0x...",
      "storage": {
        "0x...slot": "0x...value"
      }
    }
  }
}

Field	Type	Description
`balance`	`string`	Net balance change as a signed decimal string.
`nonce`	`uint64`	New account nonce, when changed.
`code`	`bytes`	New contract code or delegation bytes, when changed.
`storage`	`object<hash,hash>`	New storage values keyed by slot hash.

Schema: Subslot, FirstSubslotStart, and BlockParams

Subslot is the notification payload for tool_subscribe subslots.

{
  "id": "0x...",
  "txs": ["0x..."],
  "blockTime": 0,
  "blockParent": "0x...",
  "index": 0,
  "txsSize": 0,
  "gasUsed": 0,
  "accesses": {},
  "stateDiff": { "accounts": {} },
  "receipts": []
}

Field	Type	Description
`id`	`hash`	Subslot identifier.
`txs`	`hash[]`	Transaction hashes accepted in the subslot.
`blockTime`	`uint64`	Target block timestamp.
`blockParent`	`hash`	Target parent block hash.
`index`	`uint8`	Subslot index within the block.
`txsSize`	`uint64`	Total transaction size in bytes.
`gasUsed`	`uint64`	Gas used by accepted transactions.
`accesses`	`Accesses`	Combined read/write footprint.
`stateDiff`	`StateDiff` `\\| null`	Combined state changes.
`receipts`	`Receipt[]`	Ethereum receipts for executed transactions.

FirstSubslotStart is the notification payload for tool_subscribe firstSubslotStart.

{
  "blockParent": "0x...",
  "blockTime": 0,
  "at": "2026-01-01T00:00:00Z"
}

Field	Type	Description
`blockParent`	`hash`	Parent block for the slot.
`blockTime`	`uint64`	Slot block timestamp.
`at`	`time`	Scheduled wall-clock time for the first subslot.

BlockParams is the result for tool_nextBlockParams.

{
  "reservedGas": 0,
  "reservedSize": 0,
  "sealOffset": 0
}

Field	Type	Description
`reservedGas`	`uint64`	Gas reserved for non-TOOL block assembly.
`reservedSize`	`uint64`	Block byte size reserved for non-TOOL block assembly.
`sealOffset`	`int64`	Block seal offset encoded as nanoseconds.

Schema: GetAttestationRequest and GetAttestationResponse

{
  "userNonce": "00112233445566778899aabbccddeeff",
  "certScope": "tool"
}

Field	Type	Required	Description
`userNonce`	`hex string`	Yes	Caller-generated freshness nonce. Must decode to at least 16 bytes.
`certScope`	`string`	Yes	TLS certificate scope name to bind into the attestation.

{
  "quote": {},
  "tlsCertFingerprint": "0x...",
  "nonce": "0x..."
}

Field	Type	Description
`quote`	`object`	TEE collateral response used by the verifier.
`tlsCertFingerprint`	`hex string`	SHA-256 fingerprint of the TLS certificate served for `certScope`.
`nonce`	`hex string`	`Keccak256(userNonce \|\| tlsCertPubKeyDER)[:16]`, returned for verifier recomputation.

eth_sendBundle

`eth_sendBundle`¶

JSON-RPC eth namespace Source ingress

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.

RequestResult

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

Parameter	Type	Description
`params[0]`	`SendBundleArgs`	Source bundle request.

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

Result field	Type	Description
`bundleHash`	`hash`	Commitment id created from the accepted source bundle.

Common rejection cases:

Case	Behavior
TOOL is not enabled or not preconfirmed for the target block.	Reject with an RPC error.
Node is not in P2P TOOL mode.	Reject as unavailable in WS mode.
`txs` is empty.	Reject as an invalid bundle.
Any transaction is a blob transaction.	Reject; blob transactions are not supported on this path.
`revertingTxHashes` contains a hash not present in `txs`.	Reject.
`callbackUrl` is malformed.	Reject before bundle processing.
Timestamp or block target does not match current TOOL state.	Reject.

tool_sendBundle

`tool_sendBundle`¶

JSON-RPC tool namespace Searcher submission

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 simulates the bundle, validates resource limits, stores the resulting commitment in the TOOL pool, propagates it, and may trigger callback routing when same-origin policy allows.

RequestResult

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

Parameter	Type	Description
`params[0]`	`ToolBundle`	Native TOOL bundle request. At least one base commitment or one new transaction is required.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "id": "0x...",
    "blockTime": 0,
    "blockParent": "0x...",
    "subslot": 0,
    "expirySubslot": 14,
    "txsSize": 0,
    "gasUsed": 0,
    "maxGasLimit": 0,
    "fees": "0",
    "accesses": {},
    "stateDiff": { "accounts": {} }
  }
}

Result field	Type	Description
`result`	`Commitment`	Full commitment object created from the native bundle.

Common rejection cases:

Case	Behavior
`basedCommitments` and `newTxs` are both empty.	Reject as an empty transaction list.
Any `newTxs` transaction is a blob transaction.	Reject.
Provided `blockTime`, `blockParent`, or `subslot` does not match current TOOL state.	Reject.
A base commitment is unknown, future-dated, expired, or targets a different parent.	Reject.
Resulting size or gas exceeds current block/subslot limits.	Reject.

tool_simulateBundle

`tool_simulateBundle`¶

JSON-RPC tool namespace Searcher simulation

Use tool_simulateBundle to evaluate the same native ToolBundle shape used by tool_sendBundle without adding the result to the pool and without propagating it to peers.

RequestResult

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

Parameter	Type	Description
`params[0]`	`ToolBundle`	Native TOOL bundle request. Same schema as `tool_sendBundle`.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "id": "0x...",
    "blockTime": 0,
    "blockParent": "0x...",
    "subslot": 0,
    "expirySubslot": 14,
    "txsSize": 0,
    "gasUsed": 0,
    "maxGasLimit": 0,
    "fees": "0",
    "accesses": {},
    "stateDiff": { "accounts": {} }
  }
}

Result field	Type	Description
`result`	`Commitment`	Simulated commitment object. It is not submitted or propagated.

tool_nextBlockParams

`tool_nextBlockParams`¶

JSON-RPC tool namespace Block constraints

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

RequestResult

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

Parameter	Type	Description
`params[0]`	`hash`	Parent block hash expected by the caller. Must match current TOOL state.
`params[1]`	`uint64`	Block timestamp expected by the caller. Must match current TOOL state.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "reservedGas": 0,
    "reservedSize": 0,
    "sealOffset": 0
  }
}

Result field	Type	Description
`reservedGas`	`uint64`	Gas reserved for non-TOOL block assembly.
`reservedSize`	`uint64`	Byte size reserved for non-TOOL block assembly.
`sealOffset`	`int64`	Seal offset encoded as nanoseconds.

tool_subscribe

`tool_subscribe`¶

WebSocket JSON-RPC tool namespace Events

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

RequestResultCommitments subscriptionSubslots subscriptionNext headers subscriptionFirst subslot start subscription

Topic	Parameters	Notification payload	Use case
`commitments`	`["commitments", {}]` or `["commitments", {"0x...address": true}]`	`Commitment`	Receive commitment events. Address filters match storage writes for the listed addresses. Use `{}` for all commitments.
`subslots`	`["subslots"]`	`Subslot`	Observe accepted subslot events.
`nextHeaders`	`["nextHeaders"]`	Ethereum `Header`	Observe the header currently being built.
`firstSubslotStart`	`["firstSubslotStart"]`	`FirstSubslotStart`	Observe the scheduled first subslot start after consensus bootstrap.

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

Result source	Type	Description
`tool_subscribe` result	`subscriptionId`	Subscription id returned by the initial JSON-RPC response.
`tool_subscription.params.subscription`	`subscriptionId`	Id of the subscription that produced a notification.
`tool_subscription.params.result`	`Commitment`, `Subslot`, Ethereum `Header`, or `FirstSubslotStart`	Topic-specific event payload.
`tool_unsubscribe` result	`boolean`	`true` when a live subscription was cancelled.

{
  "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": ["firstSubslotStart"]
}

eth_call / eth_getTransactionCount / eth_getTransactionReceipt / eth_getBlockByHash

Preconfirmed `eth_*` Overrides¶

JSON-RPC eth namespace Compatibility

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.

RequestResult

Method	Standard parameters
`eth_call`	Transaction call object, block selector, optional state overrides, optional block overrides.
`eth_getTransactionCount`	Address, block selector.
`eth_getTransactionReceipt`	Transaction hash.
`eth_getBlockByHash`	Block hash, `fullTx` boolean.

Method	TOOL result behavior
`eth_call`	Executes the call against TOOL preconfirmed state when available. Revert handling matches the normal `eth_call` path.
`eth_getTransactionCount`	Returns the TOOL preconfirmed nonce when available. Falls back to the normal nonce otherwise.
`eth_getTransactionReceipt`	Returns a standard receipt for TOOL-layer accepted subslot transactions when available. Falls back to the normal receipt otherwise.
`eth_getBlockByHash`	Returns a standard block object for a TOOL preconfirmed block view when available. Falls back to the normal block lookup otherwise.

Integration guidance

Treat these as compatibility overrides, not separate TOOL methods. Clients can keep standard Ethereum call shapes and use explicit block selectors where they need preconfirmed state.

tee_getAttestation

`tee_getAttestation`¶

JSON-RPC tee namespace Verification

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.

RequestResult

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

Parameter	Type	Description
`params[0]`	`GetAttestationRequest`	Freshness challenge and TLS certificate scope.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "quote": {},
    "tlsCertFingerprint": "...",
    "nonce": "0x..."
  }
}

Result field	Type	Description
`quote`	`object`	TEE collateral response used by the verifier.
`tlsCertFingerprint`	`hex string`	SHA-256 fingerprint of the TLS certificate served for `certScope`.
`nonce`	`hex string`	`Keccak256(userNonce \|\| tlsCertPubKeyDER)[:16]`, returned for verifier recomputation.

Verifier checklist:

Check	Reason
`userNonce` is freshly generated and at least 16 bytes.	Prevents replay.
`tlsCertFingerprint` matches the certificate observed during the TLS handshake.	Proves the attested service owns the live TLS endpoint.
`nonce` equals `Keccak256(userNonce \|\| tlsCertPubKeyDER)[:16]`.	Binds the quote to the caller challenge and certificate public key.
`quote` validates against the deployment attestation policy.	Confirms the expected enclave/service identity.

Callback Receiver Contract¶

When a source bundle has a callback URL and the resulting enriched commitment is same-origin safe, TOOL sends a Flashbots-compatible JSON-RPC POST to the source callback endpoint.

POST {callbackUrl}
Content-Type: application/json
Accept: application/json
X-Flashbots-Signature: <signer-address>:<signature>

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_sendBundle",
  "params": [
    {
      "txs": ["0x...source_txs", "0x...searcher_txs"],
      "blockNumber": "0x...",
      "minTimestamp": 0,
      "maxTimestamp": 0,
      "revertingTxHashes": []
    }
  ]
}

Requirement	Description
Method	Callback receivers should accept `eth_sendBundle` with `SendBundleArgs`.
Signature header	TOOL signs the JSON-RPC request body and sends `X-Flashbots-Signature`.
Timeout	TOOL uses a 5-second callback timeout.
Success response	HTTP status must be below `300`, and the JSON-RPC response must not contain an `error`.
Response size	TOOL reads at most 64 KiB of the callback response body.

MEV-Boost Builder HTTP¶

The relay surface is HTTP, not JSON-RPC. Endpoints are MEV-Boost-compatible and are served by TOOL's in-process relay.

Endpoint	Method	Request	Response	Use case
`/eth/v1/builder/status`	`GET`	None	`200 OK`	Health check.
`/eth/v1/builder/validators`	`POST`	Signed validator registrations	`200 OK`	Register validators and optional block seal offset.
`/eth/v1/builder/header/{slot}/{parentHash}/{pubKey}`	`GET`	Path params	Versioned signed builder bid, `204`, or `404`	Retrieve a builder bid.
`/eth/v1/builder/blinded_blocks`	`POST`	Signed blinded beacon block	Versioned payload response	Submit blinded block and receive payload.
`/eth/v2/builder/blinded_blocks`	`POST`	Signed blinded beacon block	`202 Accepted`	Submit blinded block using the v2 path.

Relay format and parameter notes:

Item	Description
`Content-Type` / `Accept`	Supports `application/json` and `application/octet-stream`. Octet-stream uses SSZ.
`Eth-Consensus-Version`	Set on successful header and payload responses.
`block_seal_offset_ms`	Optional query parameter on `/validators`. Must be no more than `4000` ms.
`slot`	Decimal slot number in the header path.
`parentHash`	`0x`-encoded 32-byte parent hash in the header path.
`pubKey`	`0x`-encoded 48-byte validator public key in the header path.
`X-Timeout-Ms` and `Date-Milliseconds`	Optional request headers used to derive a header-request deadline.

Implementation Notes¶

Area	Current behavior
Blob transactions	Rejected for `eth_sendBundle`, `tool_sendBundle`, and `tool_simulateBundle`.
Native bundle field name	The JSON field for base commitments is `basedCommitments`. Role guides may use "based" as conceptual shorthand.
Commitment transaction hashes	Commitment JSON includes `id` and execution metadata, but does not include the internal `txs` hash list.
Commitment trimming	Large or over-gas commitment payloads may omit `logs` and set `StateDiff`-backed `stateDiff` to `null`.
Commitment filters	`tool_subscribe commitments` address filters match storage writes, not every read or account-level access.
Callback routing	Same-origin callback safety is stricter than internal TOOL validity. Mixed-origin private flow can remain useful internally without being returned to one external source.

TOOL Reference¶

Method Index¶

Conventions¶

Shared Schemas¶

eth_sendBundle¶

tool_sendBundle¶

tool_simulateBundle¶

tool_nextBlockParams¶

tool_subscribe¶

Preconfirmed eth_* Overrides¶

tee_getAttestation¶

Callback Receiver Contract¶

MEV-Boost Builder HTTP¶

Implementation Notes¶

`eth_sendBundle`¶

`tool_sendBundle`¶

`tool_simulateBundle`¶

`tool_nextBlockParams`¶

`tool_subscribe`¶

Preconfirmed `eth_*` Overrides¶

`tee_getAttestation`¶