RPC Reference

#Relay API Spec

MEV-Boost Relay API specification v1.

The Flashbots relay is open source: https://github.com/flashbots/mev-boost-relay

A relay has several responsibilities:

• APIs for proposers (builder-spec), block builders and data transparency
• Handling validator registrations and block proposals in a scalable manner
• Block escrow, data availability, redundancy
• Simulate and verify blocks sent by block-builders, rate-limit if necessary
  • correct amount of fees paid to most recent feeRecipient of validator
  • correct block attributes and transactions
  • within the gasLimit requested by the validator

#Data types

A reference implementation of the data types with correct SSZ encoding and signing routines can be found in this repository: https://github.com/flashbots/go-boost-utils

builder-specs and beacon-APIs">#builder-specs and beacon-APIs

• ValidatorRegistration
• SignedBuilderBid
• SignedBlindedBeaconBlock
• ExecutionPayload

#BidTrace

Represents public information about a block sent by a builder to the relay, or from the relay to the proposer. Depending on the context, value might represent the claimed value by a builder (not necessarily a value confirmed by the relay).

{
	"slot": "123",
	"parent_hash": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
	"block_hash": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
	"builder_pubkey": "0x7b2cb8dd64e0aafe7ea7b6c95065c9364cf99d38470c12ee807d55f7de1529ad29ce2c422e0b65e3d5a05c02caca249",
	"proposer_pubkey": "0x8a1d7b8dd64e0aafe7ea7b6c95065c9364cf99d38470c12ee807d55f7de1529ad29ce2c422e0b65e3d5a05c02caca249",
	"proposer_fee_recipient": "0x2b7a7b8dd64e0aafe7ea7b6c95065c9364cf99d38470c12ee807d55f7de1529ad29ce2c422e0b65e3d5a05c02caca249",
	"gas_used": "3371033",
	"gas_limit": "30000000",
	"value": "1234567"
}

See also the reference implementation of BidTrace

#SignedBidTrace

{
	"message": BidTrace
  "signature": "0x..."
}

Note: BLS signature using the builder domain (relative to the genesis fork and with a zero genesis validators root).

See also the reference implementation of SignedBidTrace

#ValidatorRegistration

{
	"message": {
		"fee_recipient": "0xabcf8e0d4e9587369b2301d0790347320302cc09",
		"gas_limit": "1",
		"timestamp": "1",
		"pubkey": "0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a"
	},
	"signature": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505"
}

(reference implementation)

#ErrorResponse

All API errors follow this schema:

{
	"code": 400,
	"message": "description about the error"
}

#Proposer API

Standard APIs as per builder spec:

• registerValidator: POST /eth/v1/builder/validators
• getHeader: GET /eth/v1/builder/header/{slot}/{parent_hash}/{pubkey} - Get an execution payload header.
• submitBlindedBlock: POST /eth/v1/builder/blinded_blocks - Submit a signed blinded block and get unblinded execution payload.
• status: GET /eth/v1/builder/status

#Block Builder API

The block builder API allows block submissions to the MEV-Boost Relays. Currently, the Flashbots relays for Goerli, Sepolia and Mainnet allow submissions by external builders.

#getValidators

Get a list of validator registrations for validators scheduled to propose in the current and next epoch.

#GET /relay/v1/builder/validators

Success Response

Array of validatorRegistrations for the current and next epoch. Each entry includes a slot and the validator with assigned duty (if he submitted a registration previously). Slots without a registered validator are omitted.

Payload:

[{
	"slot": "123",
	"entry": ValidatorRegistration
},
...]

Example - API on Goerli: https://builder-relay-goerli.flashbots.net/relay/v1/builder/validators

#submitBlock

Submit a new block to the relay.

Notes:

• Builder signature is over SSZ encoded message (for accountability). The message doesn’t include the transactions and can be made public with the (Data API), allowing anyone to verify the builder signature.

POST /relay/v1/builder/blocks">#POST /relay/v1/builder/blocks

Request payload:

// Type:
{
  "signature": "0x8c795f751f812eabbabdee85100a06730a9904a4b53eedaa7f546fe0e23cd75125e293c6b0d007aa68a9da4441929d16072668abb4323bb04ac81862907357e09271fe414147b3669509d91d8ffae2ec9c789a5fcd4519629b8f2c7de8d0cce9"
	"message": BidTrace
  "execution_payload": ExecutionPayload
}

// Example:
{
  "signature": "0x8c795f751f812eabbabdee85100a06730a9904a4b53eedaa7f546fe0e23cd75125e293c6b0d007aa68a9da4441929d16072668abb4323bb04ac81862907357e09271fe414147b3669509d91d8ffae2ec9c789a5fcd4519629b8f2c7de8d0cce9"
	"message": {
	  "slot": "123",
    "parent_hash": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
    "block_hash": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
    "builder_pubkey": "0x7b2acb8dd64e0aafe7ea7b6c95065c9364cf99d38470c12ee807d55f7de1529ad29ce2c422e0b65e3d5a05c02caca249",
    "proposer_pubkey": "0x8a1d7b8dd64e0aafe7ea7b6c95065c9364cf99d38470c12ee807d55f7de1529ad29ce2c422e0b65e3d5a05c02caca249",
    "proposer_fee_recipient": "0xf1469083b2cbab4d1f648176bf8e26e581ebabd4",
    "gas_used": "3371033",
    "gas_limit": "30000000",
		"value": "1234567",
	},
  "execution_payload": {
    "parent_hash": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
    "fee_recipient": "0xabcf8e0d4e9587369b2301d0790347320302cc09",
    "state_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
    "receipts_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
    "logs_bloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
    "prev_randao": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
    "block_number": "1",
    "gas_used": "3371033",
    "gas_limit": "30000000",
    "timestamp": "1",
    "extra_data": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
    "base_fee_per_gas": "1",
    "block_hash": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
    "transactions": [
        "0x02f878831469668303f51d843b9ac9f9843b9aca0082520894c93269b73096998db66be0441e836d873535cb9c8894a19041886f000080c001a031cc29234036afbf9a1fb9476b463367cb1f957ac0b919b69bbc798436e604aaa018c4e9c3914eb27aadd0b91e10b18655739fcf8c1fc398763a9f1beecb8ddc86"
    ]
  }
}

(See also the reference implementation for BuilderSubmitBlockRequest)

Notes

• execution_payload is the ExecutionPayload from the CL Bellatrix spec.
• The relay will simulate the block to verify properties and proposer payment in the payment transaction from builder to proposer feeRecipient at the end of block.

Success response:

Status code 200

The block was received (but not yet checked for correctness, because simulation happens asynchronously). The response contains a receipt which includes a timestamp and [BidTrace](https://www.notion.so/Relay-API-Spec-5fb0819366954962bc02e81cb33840f5) (the response is not yet implemented).

{
  "message": {
    "receive_timestamp": "1655906415",
    "bid_trace": [BidTrace](https://www.notion.so/Relay-API-Spec-5fb0819366954962bc02e81cb33840f5),
  },
  "signature": "0x..."
}

Notes:

• For getting started with building, see also the example builder implementation https://github.com/flashbots/boost-geth-builder

#Data API

Provides data about received blocks from builders and header/payload queries from proposers.

#ProposerPayloadsDelivered

This API provides BidTraces for payloads that were delivered to proposers.

#GET /relay/v1/data/bidtraces/proposer_payload_delivered

Optional query arguments:

• slot: a specific slot
• cursor: a slot cursor, where the entries start at cursor and go backwards until limit amount of entries is reached (note only one of slot or cursor can be used at a time)
• limit: maximum number of entries (200 max)
• block_hash: search for a specific blockhash
• block_number: search for a specific EL block number
• proposer_pubkey: filter results by a proposer public key
• order_by:
  • -value to sort result by descending value (highest value first)
  • value to sort result by ascending value (lowest value first)

The response payload is an array of BidTrace objects :

[[BidTrace](https://www.notion.so/Relay-API-Spec-5fb0819366954962bc02e81cb33840f5)]

Note: In case of reorgs there could be multiple bids per slot.

This API is live on all our relays: https://builder-relay-goerli.flashbots.net/relay/v1/data/bidtraces/proposer_payload_delivered?limit=10 (rate limit is 60 req/min/ip)

#BuilderBlocksReceived

This API provides BidTraces for the builder block submission for a given slot (that were verified successfully).

GET /relay/v1/data/bidtraces/builder_blocks_received

Optional query arguments:

• slot: a specific slot
• limit: maximum number of entries (200 max)
• block_hash: search for a specific blockhash
• block_number: search for a specific EL block number

The response payload is an array of BidTraceWithTimestamp objects:

[[BidTrace](https://www.notion.so/Relay-API-Spec-5fb0819366954962bc02e81cb33840f5)WithTimestamp]

This API is live on all our relays: https://builder-relay-goerli.flashbots.net/relay/v1/data/bidtraces/builder_blocks_received?limit=5 (rate limit is 60 req/min/ip)

#ValidatorRegistration

Return the latest validator registration for a given pubkey. Useful to check whether your own registration was successful.

GET /relay/v1/data/validator_registration?pubkey=_pubkey_

The response payload is either an error or a validator registration:

ValidatorRegistration

Example URL

#Relay Infrastructure

example simplified infrastructure diagram:

Notes:

• Validator registrations need to be handled in a scalable fashion, independently of the other proposer APIs (getHeader, submitBlindedBlock). The burst of up to 1M validator registrations each epoch requires a lot of resources to process, verify and save to a database.

• Block submissions need to be verified by simulating the full block, and the relay needs to be prepared to throttle any individual builder in case of spam or other issues (continuous invalid blocks or incorrect proposer payment).

• Operating a relay is infrastructure-intensive, and bugs can negatively impact Eth2 consensus. One of the solutions Flashbots is working on is a service called Relay Monitor, which tracks relay performance and helps proposers interact only with healthy ones.