RPC & Relay Reference

Relay Endpoints

network json_rpc enr_rpc
homestead mainnet-relay.securerpc.com/ 0x98650451ba02064f7b000f5768cf0cf4d4e492317d82871bdc87ef841a0743f69f0f1eea11168503240ac35d101c9135@mainnet-relay.securerpc.com/
goerli goerli-relay.securerpc.com/ 0x8a72a5ec3e2909fff931c8b42c9e0e6c6e660ac48a98016777fc63a73316b3ffb5c622495106277f8dbcc17a06e92ca3@goerli-relay.securerpc.com/

#Relay overview

MEV-Boost Relay API specification v1.0.1

SecureRpc implements a Flashbots Relay equivalent API. You can see the Flashbots reference implementation is open source: https://github.com/flashbots/mev-boost-relay

MEV Relays handle Ethereum Validator MEV Boost interactions alon with managing: - ensuring the correct amount of fees paid to most recent feeRecipient of validator - validating that the correct block attributes and transactions are included - check that blocks are within the gasLimit requested by the validator

#Relay v1.0 API Endpoints

MEV Relay v1.0 API endpoints can be broken down into the following 3

Proposer API Endpoint
pathStatus /eth/v1/builder/status
pathRegisterValidator /eth/v1/builder/validators
pathGetHeader /eth/v1/builder/header/{slot:[0-9]+}/{parent_hash:0x[a-fA-F0-9]+}/{pubkey:0x[a-fA-F0-9]+}
pathGetPayload /eth/v1/builder/blinded_blocks
Block Builder Endpoint
pathBuilderGetValidators /relay/v1/builder/validators
pathSubmitNewBlock /relay/v1/builder/blocks
Data API Endpoint
pathDataProposerPayloadDelivered /relay/v1/data/bidtraces/proposer_payload_delivered
pathDataBuilderBidsReceived /relay/v1/data/bidtraces/builder_blocks_received
pathDataValidatorRegistration /relay/v1/data/validator_registration

#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

#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)

#Error and Exceptions Response Handling

Code Message Meaning
-32000 Server error Generic client error while processing request.
-32001 Unknown hash No block with the provided hash is known.
-32002 Unknown validator Unknown validator.
-32003 Unknown fee recipient No known mapping between validator and fee recipient.
-32004 Unknown block Block does not match the provided header.
-32005 Invalid signature Provided signature is invalid.
-32006 Invalid timestamp Provided timestamp was invalid.
-32600 Invalid request The JSON sent is not a valid Request object.
-32601 Method not found The method does not exist / is not available.
-32602 Invalid params Invalid method parameter(s).
-32603 Internal error Internal JSON-RPC error.
-32700 Parse error Invalid JSON was received by the server.

All API errors follow this schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "name": "Error Encoding Schema",
  "type": "object",
  "properties": {
    "code": {
      "type": "integer"
    },
    "message": {
      "type": "string",
      "pattern": "^0x([1-9a-f]+[0-9a-f]*|0)$"   
    }
  },
  "required": [
    "code",
    "message"
  ]
}

Example

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

#Proposer API

Proposer API Endpoint
pathStatus /eth/v1/builder/status
pathRegisterValidator /eth/v1/builder/validators
pathGetHeader /eth/v1/builder/header/{slot:[0-9]+}/{parent_hash:0x[a-fA-F0-9]+}/{pubkey:0x[a-fA-F0-9]+}
pathGetPayload /eth/v1/builder/blinded_blocks

Standard APIs as per builder spec:

#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:

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

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:


#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:

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:

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: