Relay REST API¶
Extended from the Relay spec
Relay API dev¶
API specification for MEV-Boost PBS relays.
Contact: GitHub Repository
License: CC0-1.0
Servers¶
| Description | URL |
|---|---|
| {server_url} | {server_url} |
Builder¶
GET /relay/v1/builder/validators¶
Get a list of validator registrations for validators scheduled to propose in the current and next epoch.
Description
-
Used by builders to know when to submit bids for an upcoming proposal.
-
Returns an array of validator registrations for the current and next epoch.
-
Each entry includes a slot and the validator with assigned duty.
-
Slots without a registered validator are omitted.
Response 200 OK
[
{
"slot": "1",
"validator_index": "1",
"entry": {
"message": {
"fee_recipient": "0xAbcF8e0d4e9587369b2301D0790347320302cc09",
"gas_limit": "1",
"timestamp": "1",
"pubkey": "0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a"
},
"signature": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505"
}
}
]
Schema of the response body
{
"type": "array",
"items": {
"type": "object",
"properties": {
"slot": {
"type": "string",
"example": "1"
},
"validator_index": {
"type": "string",
"example": "1"
},
"entry": {
"type": "object",
"description": "The `SignedValidatorRegistration` object from the Builder API specification.",
"required": [
"message",
"signature"
],
"properties": {
"message": {
"type": "object",
"description": "The `ValidatorRegistration` object from the Builder API specification.",
"required": [
"fee_recipient",
"gas_limit",
"timestamp",
"pubkey"
],
"properties": {
"fee_recipient": {
"description": "Address to receive fees from the block.",
"type": "string",
"format": "hex",
"example": "0xAbcF8e0d4e9587369b2301D0790347320302cc09",
"pattern": "^0x[a-fA-F0-9]{40}$"
},
"gas_limit": {
"description": "Preferred gas limit of validator.",
"type": "string",
"example": "1"
},
"timestamp": {
"description": "Unix timestamp of registration.",
"type": "string",
"example": "1"
},
"pubkey": {
"description": "BLS public key of validator.",
"type": "string",
"format": "hex",
"pattern": "^0x[a-fA-F0-9]{96}$",
"example": "0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a"
}
}
},
"signature": {
"type": "string",
"format": "hex",
"pattern": "^0x[a-fA-F0-9]{192}$",
"example": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505"
}
}
}
}
}
}
POST /relay/v1/builder/blocks¶
Submit a new block to the relay.
Description
-
Blocks can be submitted as JSON or SSZ, and optionally GZIP encoded. To be clear, there are four options: JSON, JSON+GZIP, SSZ, SSZ+GZIP. If JSON, the content type should be
application/json. If SSZ, the content type should beapplication/octet-stream. -
To enable GZIP compression for the request body, the HTTP content encoding should be
gzip. Compression is optional. -
The relay will simulate the block to verify properties and proposer payment in the payment transaction from builder to proposer
fee_recipientat the end of block. -
For accountability, builder signature is over the SSZ encoded
message. -
The
message, which does not include the transactions, will be made public via the data API, allowing anyone to verify the builder signature. -
Any new submission by a builder will overwrite a previous one by the same
builder_pubkey, even if it is less profitable.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
cancellations |
query | string | No | If set to 1, opt into bid cancellations. |
Request body
{
"message": {
"slot": "1",
"parent_hash": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"block_hash": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"builder_pubkey": "0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a",
"proposer_fee_recipient": "0xabcf8e0d4e9587369b2301d0790347320302cc09",
"gas_limit": "1",
"gas_used": "1",
"value": "1"
},
"execution_payload": {
"parent_hash": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"fee_recipient": "0xabcf8e0d4e9587369b2301d0790347320302cc09",
"state_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"receipts_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"logs_bloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
"prev_randao": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"block_number": "1",
"gas_limit": "1",
"gas_used": "1",
"timestamp": "1",
"extra_data": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"base_fee_per_gas": "1",
"block_hash": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"transactions": [
"0x02f878831469668303f51d843b9ac9f9843b9aca0082520894c93269b73096998db66be0441e836d873535cb9c8894a19041886f000080c001a031cc29234036afbf9a1fb9476b463367cb1f957ac0b919b69bbc798436e604aaa018c4e9c3914eb27aadd0b91e10b18655739fcf8c1fc398763a9f1beecb8ddc86"
]
},
"signature": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505"
}
{
"message": {
"slot": "1",
"parent_hash": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"block_hash": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"builder_pubkey": "0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a",
"proposer_fee_recipient": "0xabcf8e0d4e9587369b2301d0790347320302cc09",
"gas_limit": "1",
"gas_used": "1",
"value": "1"
},
"execution_payload": {
"parent_hash": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"fee_recipient": "0xabcf8e0d4e9587369b2301d0790347320302cc09",
"state_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"receipts_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"logs_bloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
"prev_randao": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"block_number": "1",
"gas_limit": "1",
"gas_used": "1",
"timestamp": "1",
"extra_data": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"base_fee_per_gas": "1",
"block_hash": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"transactions": [
"0x02f878831469668303f51d843b9ac9f9843b9aca0082520894c93269b73096998db66be0441e836d873535cb9c8894a19041886f000080c001a031cc29234036afbf9a1fb9476b463367cb1f957ac0b919b69bbc798436e604aaa018c4e9c3914eb27aadd0b91e10b18655739fcf8c1fc398763a9f1beecb8ddc86"
],
"withdrawals": [
{
"index": "1",
"validator_index": "1",
"address": "0xabcf8e0d4e9587369b2301d0790347320302cc09",
"amount": "32000000000"
}
]
},
"signature": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505"
}
{
"message": {
"slot": "1",
"parent_hash": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"block_hash": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"builder_pubkey": "0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a",
"proposer_fee_recipient": "0xabcf8e0d4e9587369b2301d0790347320302cc09",
"gas_limit": "1",
"gas_used": "1",
"value": "1"
},
"execution_payload": {
"parent_hash": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"fee_recipient": "0xabcf8e0d4e9587369b2301d0790347320302cc09",
"state_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"receipts_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"logs_bloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
"prev_randao": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"block_number": "1",
"gas_limit": "1",
"gas_used": "1",
"timestamp": "1",
"extra_data": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"base_fee_per_gas": "1",
"block_hash": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"transactions": [
"0x02f878831469668303f51d843b9ac9f9843b9aca0082520894c93269b73096998db66be0441e836d873535cb9c8894a19041886f000080c001a031cc29234036afbf9a1fb9476b463367cb1f957ac0b919b69bbc798436e604aaa018c4e9c3914eb27aadd0b91e10b18655739fcf8c1fc398763a9f1beecb8ddc86"
],
"withdrawals": [
{
"index": "1",
"validator_index": "1",
"address": "0xabcf8e0d4e9587369b2301d0790347320302cc09",
"amount": "32000000000"
}
]
},
"blobs_bundle": {
"commitments": [
"0x8dab030c51e16e84be9caab84ee3d0b8bbec1db4a0e4de76439da8424d9b957370a10a78851f97e4b54d2ce1ab0d686f"
],
"proofs": [
"0xb4021b0de10f743893d4f71e1bf830c019e832958efd6795baf2f83b8699a9eccc5dc99015d8d4d8ec370d0cc333c06a"
],
"blobs": [
"0x24564723180fcb3d994104538d351c8dcbde12d541676bb736cf678018ca4739"
]
},
"signature": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505"
}
Schema of the request body
{
"oneOf": [
{
"allOf": [
{
"type": "object",
"properties": {
"message": {
"type": "object",
"properties": {
"slot": {
"type": "string",
"example": "1"
},
"parent_hash": {
"type": "string",
"format": "hex",
"example": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"pattern": "^0x[a-fA-F0-9]{64}$"
},
"block_hash": {
"type": "string",
"format": "hex",
"example": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"pattern": "^0x[a-fA-F0-9]{64}$"
},
"builder_pubkey": {
"type": "string",
"format": "hex",
"pattern": "^0x[a-fA-F0-9]{96}$",
"description": "The validator's BLS public key, uniquely identifying them. _48-bytes, hex encoded with 0x prefix, case insensitive._",
"example": "0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a"
},
"proposer_pubkey": {
"type": "string",
"format": "hex",
"pattern": "^0x[a-fA-F0-9]{96}$",
"description": "The validator's BLS public key, uniquely identifying them. _48-bytes, hex encoded with 0x prefix, case insensitive._",
"example": "0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a"
},
"proposer_fee_recipient": {
"type": "string",
"format": "hex",
"description": "An address on the execution (Ethereum 1) network.",
"example": "0xAbcF8e0d4e9587369b2301D0790347320302cc09",
"pattern": "^0x[a-fA-F0-9]{40}$"
},
"gas_limit": {
"type": "string",
"example": "1"
},
"gas_used": {
"type": "string",
"example": "1"
},
"value": {
"type": "string",
"example": "1"
}
}
},
"signature": {
"type": "string",
"format": "hex",
"pattern": "^0x[a-fA-F0-9]{192}$",
"example": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505"
}
}
},
{
"type": "object",
"properties": {
"execution_payload": {
"allOf": [
{
"type": "object",
"description": "The [`ExecutionPayload`](https://github.com/ethereum/consensus-specs/blob/v1.3.0/specs/bellatrix/beacon-chain.md#executionpayload) object from the CL Bellatrix spec.",
"required": [
"parent_hash",
"fee_recipient",
"state_root",
"receipts_root",
"logs_bloom",
"prev_randao",
"block_number",
"gas_limit",
"gas_used",
"timestamp",
"extra_data",
"base_fee_per_gas",
"block_hash"
],
"properties": {
"parent_hash": {
"type": "string",
"format": "hex",
"example": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"pattern": "^0x[a-fA-F0-9]{64}$"
},
"fee_recipient": {
"type": "string",
"format": "hex",
"description": "An address on the execution (Ethereum 1) network.",
"example": "0xAbcF8e0d4e9587369b2301D0790347320302cc09",
"pattern": "^0x[a-fA-F0-9]{40}$"
},
"state_root": {
"type": "string",
"format": "hex",
"example": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"pattern": "^0x[a-fA-F0-9]{64}$"
},
"receipts_root": {
"type": "string",
"format": "hex",
"example": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"pattern": "^0x[a-fA-F0-9]{64}$"
},
"logs_bloom": {
"type": "string",
"format": "hex",
"example": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
"pattern": "^0x[a-fA-F0-9]{512}$"
},
"prev_randao": {
"type": "string",
"format": "hex",
"example": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"pattern": "^0x[a-fA-F0-9]{64}$"
},
"block_number": {
"type": "string",
"example": "1"
},
"gas_limit": {
"type": "string",
"example": "1"
},
"gas_used": {
"type": "string",
"example": "1"
},
"timestamp": {
"type": "string",
"example": "1"
},
"extra_data": {
"type": "string",
"format": "hex",
"description": "Extra data on the execution (Ethereum 1) network.",
"example": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"pattern": "^0x[a-fA-F0-9]{0,64}$"
},
"base_fee_per_gas": {
"type": "string",
"example": "1"
},
"block_hash": {
"type": "string",
"format": "hex",
"example": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"pattern": "^0x[a-fA-F0-9]{64}$"
}
}
},
{
"type": "object",
"required": [
"transactions"
],
"properties": {
"transactions": {
"type": "array",
"items": {
"type": "string",
"format": "hex",
"description": "A transaction on the execution (Ethereum 1) network.",
"example": "0x02f878831469668303f51d843b9ac9f9843b9aca0082520894c93269b73096998db66be0441e836d873535cb9c8894a19041886f000080c001a031cc29234036afbf9a1fb9476b463367cb1f957ac0b919b69bbc798436e604aaa018c4e9c3914eb27aadd0b91e10b18655739fcf8c1fc398763a9f1beecb8ddc86",
"pattern": "^0x[a-fA-F0-9]{0,2147483648}$"
},
"maxItems": 1048576
}
}
}
]
}
}
}
]
},
{
"allOf": [
{
"type": "object",
"properties": {
"message": {
"type": "object",
"properties": {
"slot": {
"type": "string",
"example": "1"
},
"parent_hash": {
"type": "string",
"format": "hex",
"example": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"pattern": "^0x[a-fA-F0-9]{64}$"
},
"block_hash": {
"type": "string",
"format": "hex",
"example": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"pattern": "^0x[a-fA-F0-9]{64}$"
},
"builder_pubkey": {
"type": "string",
"format": "hex",
"pattern": "^0x[a-fA-F0-9]{96}$",
"description": "The validator's BLS public key, uniquely identifying them. _48-bytes, hex encoded with 0x prefix, case insensitive._",
"example": "0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a"
},
"proposer_pubkey": {
"type": "string",
"format": "hex",
"pattern": "^0x[a-fA-F0-9]{96}$",
"description": "The validator's BLS public key, uniquely identifying them. _48-bytes, hex encoded with 0x prefix, case insensitive._",
"example": "0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a"
},
"proposer_fee_recipient": {
"type": "string",
"format": "hex",
"description": "An address on the execution (Ethereum 1) network.",
"example": "0xAbcF8e0d4e9587369b2301D0790347320302cc09",
"pattern": "^0x[a-fA-F0-9]{40}$"
},
"gas_limit": {
"type": "string",
"example": "1"
},
"gas_used": {
"type": "string",
"example": "1"
},
"value": {
"type": "string",
"example": "1"
}
}
},
"signature": {
"type": "string",
"format": "hex",
"pattern": "^0x[a-fA-F0-9]{192}$",
"example": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505"
}
}
},
{
"type": "object",
"properties": {
"execution_payload": {
"allOf": [
{
"type": "object",
"description": "The [`ExecutionPayload`](https://github.com/ethereum/consensus-specs/blob/v1.3.0/specs/capella/beacon-chain.md#executionpayload) object from the CL Capella spec.",
"required": [
"parent_hash",
"fee_recipient",
"state_root",
"receipts_root",
"logs_bloom",
"prev_randao",
"block_number",
"gas_limit",
"gas_used",
"timestamp",
"extra_data",
"base_fee_per_gas",
"block_hash"
],
"properties": {
"parent_hash": {
"type": "string",
"format": "hex",
"example": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"pattern": "^0x[a-fA-F0-9]{64}$"
},
"fee_recipient": {
"type": "string",
"format": "hex",
"description": "An address on the execution (Ethereum 1) network.",
"example": "0xAbcF8e0d4e9587369b2301D0790347320302cc09",
"pattern": "^0x[a-fA-F0-9]{40}$"
},
"state_root": {
"type": "string",
"format": "hex",
"example": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"pattern": "^0x[a-fA-F0-9]{64}$"
},
"receipts_root": {
"type": "string",
"format": "hex",
"example": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"pattern": "^0x[a-fA-F0-9]{64}$"
},
"logs_bloom": {
"type": "string",
"format": "hex",
"example": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
"pattern": "^0x[a-fA-F0-9]{512}$"
},
"prev_randao": {
"type": "string",
"format": "hex",
"example": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"pattern": "^0x[a-fA-F0-9]{64}$"
},
"block_number": {
"type": "string",
"example": "1"
},
"gas_limit": {
"type": "string",
"example": "1"
},
"gas_used": {
"type": "string",
"example": "1"
},
"timestamp": {
"type": "string",
"example": "1"
},
"extra_data": {
"type": "string",
"format": "hex",
"description": "Extra data on the execution (Ethereum 1) network.",
"example": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"pattern": "^0x[a-fA-F0-9]{0,64}$"
},
"base_fee_per_gas": {
"type": "string",
"example": "1"
},
"block_hash": {
"type": "string",
"format": "hex",
"example": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"pattern": "^0x[a-fA-F0-9]{64}$"
}
}
},
{
"type": "object",
"required": [
"transactions",
"withdrawals"
],
"properties": {
"transactions": {
"type": "array",
"items": {
"type": "string",
"format": "hex",
"description": "A transaction on the execution (Ethereum 1) network.",
"example": "0x02f878831469668303f51d843b9ac9f9843b9aca0082520894c93269b73096998db66be0441e836d873535cb9c8894a19041886f000080c001a031cc29234036afbf9a1fb9476b463367cb1f957ac0b919b69bbc798436e604aaa018c4e9c3914eb27aadd0b91e10b18655739fcf8c1fc398763a9f1beecb8ddc86",
"pattern": "^0x[a-fA-F0-9]{0,2147483648}$"
},
"maxItems": 1048576
},
"withdrawals": {
"type": "array",
"items": {
"type": "object",
"required": [
"index",
"validator_index",
"address",
"amount"
],
"properties": {
"index": {
"description": "The index of the withdrawal.",
"type": "string",
"example": "1"
},
"validator_index": {
"description": "The index of the withdrawing validator.",
"type": "string",
"example": "1"
},
"address": {
"description": "The address to which the withdrawal is credited.",
"type": "string",
"format": "hex",
"example": "0xAbcF8e0d4e9587369b2301D0790347320302cc09",
"pattern": "^0x[a-fA-F0-9]{40}$"
},
"amount": {
"description": "The value withdrawn (gwei).",
"type": "string",
"example": "1"
}
}
},
"maxItems": 16
}
}
}
]
}
}
}
]
},
{
"allOf": [
{
"type": "object",
"properties": {
"message": {
"type": "object",
"properties": {
"slot": {
"type": "string",
"example": "1"
},
"parent_hash": {
"type": "string",
"format": "hex",
"example": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"pattern": "^0x[a-fA-F0-9]{64}$"
},
"block_hash": {
"type": "string",
"format": "hex",
"example": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"pattern": "^0x[a-fA-F0-9]{64}$"
},
"builder_pubkey": {
"type": "string",
"format": "hex",
"pattern": "^0x[a-fA-F0-9]{96}$",
"description": "The validator's BLS public key, uniquely identifying them. _48-bytes, hex encoded with 0x prefix, case insensitive._",
"example": "0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a"
},
"proposer_pubkey": {
"type": "string",
"format": "hex",
"pattern": "^0x[a-fA-F0-9]{96}$",
"description": "The validator's BLS public key, uniquely identifying them. _48-bytes, hex encoded with 0x prefix, case insensitive._",
"example": "0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a"
},
"proposer_fee_recipient": {
"type": "string",
"format": "hex",
"description": "An address on the execution (Ethereum 1) network.",
"example": "0xAbcF8e0d4e9587369b2301D0790347320302cc09",
"pattern": "^0x[a-fA-F0-9]{40}$"
},
"gas_limit": {
"type": "string",
"example": "1"
},
"gas_used": {
"type": "string",
"example": "1"
},
"value": {
"type": "string",
"example": "1"
}
}
},
"signature": {
"type": "string",
"format": "hex",
"pattern": "^0x[a-fA-F0-9]{192}$",
"example": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505"
}
}
},
{
"type": "object",
"description": "A wrapper object containing the ExecutionPayload and the BlobsBundle",
"required": [
"execution_payload",
"blobs_bundle"
],
"properties": {
"execution_payload": {
"allOf": [
{
"type": "object",
"description": "The [`ExecutionPayload`](https://github.com/ethereum/consensus-specs/blob/master/specs/deneb/beacon-chain.md#executionpayload) object from the CL Deneb spec.",
"properties": {
"parent_hash": {
"type": "string",
"format": "hex",
"example": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"pattern": "^0x[a-fA-F0-9]{64}$"
},
"fee_recipient": {
"type": "string",
"format": "hex",
"description": "An address on the execution (Ethereum 1) network.",
"example": "0xabcf8e0d4e9587369b2301d0790347320302cc09",
"pattern": "^0x[a-fA-F0-9]{40}$"
},
"state_root": {
"type": "string",
"format": "hex",
"example": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"pattern": "^0x[a-fA-F0-9]{64}$"
},
"receipts_root": {
"type": "string",
"format": "hex",
"example": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"pattern": "^0x[a-fA-F0-9]{64}$"
},
"logs_bloom": {
"type": "string",
"format": "hex",
"example": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
"pattern": "^0x[a-fA-F0-9]{512}$"
},
"prev_randao": {
"type": "string",
"format": "hex",
"example": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"pattern": "^0x[a-fA-F0-9]{64}$"
},
"block_number": {
"type": "string",
"example": "1"
},
"gas_limit": {
"type": "string",
"example": "1"
},
"gas_used": {
"type": "string",
"example": "1"
},
"timestamp": {
"type": "string",
"example": "1"
},
"extra_data": {
"type": "string",
"format": "hex",
"description": "Extra data on the execution (Ethereum 1) network.",
"example": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"pattern": "^0x[a-fA-F0-9]{0,64}$"
},
"base_fee_per_gas": {
"type": "string",
"example": "1"
},
"excess_data_gas": {
"type": "string",
"example": "1"
},
"block_hash": {
"type": "string",
"format": "hex",
"example": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"pattern": "^0x[a-fA-F0-9]{64}$"
}
}
},
{
"type": "object",
"properties": {
"transactions": {
"type": "array",
"items": {
"type": "string",
"format": "hex",
"description": "A transaction on the execution (Ethereum 1) network.",
"example": "0x02f878831469668303f51d843b9ac9f9843b9aca0082520894c93269b73096998db66be0441e836d873535cb9c8894a19041886f000080c001a031cc29234036afbf9a1fb9476b463367cb1f957ac0b919b69bbc798436e604aaa018c4e9c3914eb27aadd0b91e10b18655739fcf8c1fc398763a9f1beecb8ddc86",
"pattern": "^0x[a-fA-F0-9]{0,2147483648}$"
},
"maxItems": 1048576
},
"withdrawals": {
"type": "array",
"items": {
"type": "object",
"properties": {
"index": {
"description": "The index of the withdrawal.",
"type": "string",
"example": "1"
},
"validator_index": {
"description": "The index of the withdrawing validator.",
"type": "string",
"example": "1"
},
"address": {
"description": "The address to which the withdrawal is credited.",
"type": "string",
"format": "hex",
"example": "0xabcf8e0d4e9587369b2301d0790347320302cc09",
"pattern": "^0x[a-fA-F0-9]{40}$"
},
"amount": {
"description": "The value withdrawn (gwei).",
"type": "string",
"example": "1"
}
}
},
"maxItems": 16
}
}
}
]
},
"blobs_bundle": {
"type": "object",
"description": "The `BlobsBundle` object from the CL Deneb spec",
"required": [
"blobs",
"commitments",
"proofs"
],
"properties": {
"blobs": {
"type": "array",
"items": {
"type": "string",
"format": "hex",
"pattern": "^0x[a-fA-F0-9]{262144}$",
"description": "A blob is `FIELD_ELEMENTS_PER_BLOB * size_of(BLSFieldElement) = 4096 * 32 = 131072` bytes (`DATA`) representing a SSZ-encoded Blob as defined in Deneb"
},
"minItems": 0,
"maxItems": 4096
},
"commitments": {
"type": "array",
"items": {
"type": "string",
"format": "hex",
"pattern": "^0x[a-fA-F0-9]{96}$",
"description": "A G1 curve point. Same as BLS standard \"is valid pubkey\" check but also allows `0x00..00` for point-at-infinity",
"example": "0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a"
},
"minItems": 0,
"maxItems": 4096
},
"proofs": {
"type": "array",
"items": {
"type": "string",
"format": "hex",
"pattern": "^0x[a-fA-F0-9]{96}$",
"description": "A G1 curve point. Used for verifying that the `KZGCommitment` for a given `Blob` is correct."
},
"minItems": 0,
"maxItems": 4096
}
}
}
}
}
]
}
]
}
Response 200 OK
Response 400 Bad Request
Schema of the response body
{
"allOf": [
{
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"description": "Either specific error code in case of invalid request or http status code",
"type": "number",
"example": 404
},
"message": {
"description": "Message describing error",
"type": "string"
},
"stacktraces": {
"description": "Optional stacktraces, sent when node is in debug mode",
"type": "array",
"items": {
"type": "string"
}
}
}
},
{
"example": {
"code": 400,
"message": "payload for this slot was already delivered"
}
}
]
}
Response 500 Internal Server Error
Schema of the response body
{
"type": "object",
"properties": {
"code": {
"description": "Either specific error code in case of invalid request or http status code",
"type": "number",
"example": 404
},
"message": {
"description": "Message describing error",
"type": "string"
},
"stacktraces": {
"description": "Optional stacktraces, sent when node is in debug mode",
"type": "array",
"items": {
"type": "string"
}
}
}
}
Data¶
GET /relay/v1/data/bidtraces/proposer_payload_delivered¶
Get payloads that were delivered to proposers.
Description
-
Payloads become available after the relay responds to a
getPayloadrequest from the proposer. -
Query arguments are used as filters.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
block_hash |
query | string | No | A specific block hash. | |
block_number |
query | string | No | A specific block number. | |
builder_pubkey |
query | string | No | A specific builder public key. | |
cursor |
query | string | No | A starting slot for multiple results. | |
limit |
query | string | No | The number of results. | |
order_by |
query | string | No | Sort results in order of... | |
proposer_pubkey |
query | string | No | A specific proposer public key. | |
slot |
query | string | No | A specific slot. |
Response 200 OK
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
Schema of the response body
{
"type": "array",
"items": {
"allOf": [
{
"type": "object",
"properties": {
"slot": {
"type": "string",
"example": "1"
},
"parent_hash": {
"type": "string",
"format": "hex",
"example": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"pattern": "^0x[a-fA-F0-9]{64}$"
},
"block_hash": {
"type": "string",
"format": "hex",
"example": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"pattern": "^0x[a-fA-F0-9]{64}$"
},
"builder_pubkey": {
"type": "string",
"format": "hex",
"pattern": "^0x[a-fA-F0-9]{96}$",
"description": "The validator's BLS public key, uniquely identifying them. _48-bytes, hex encoded with 0x prefix, case insensitive._",
"example": "0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a"
},
"proposer_pubkey": {
"type": "string",
"format": "hex",
"pattern": "^0x[a-fA-F0-9]{96}$",
"description": "The validator's BLS public key, uniquely identifying them. _48-bytes, hex encoded with 0x prefix, case insensitive._",
"example": "0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a"
},
"proposer_fee_recipient": {
"type": "string",
"format": "hex",
"description": "An address on the execution (Ethereum 1) network.",
"example": "0xAbcF8e0d4e9587369b2301D0790347320302cc09",
"pattern": "^0x[a-fA-F0-9]{40}$"
},
"gas_limit": {
"type": "string",
"example": "1"
},
"gas_used": {
"type": "string",
"example": "1"
},
"value": {
"type": "string",
"example": "1"
}
}
},
{
"type": "object",
"properties": {
"block_number": {
"type": "string",
"example": "1"
},
"num_tx": {
"type": "string",
"example": "1"
}
}
}
]
}
}
Response 400 Bad Request
Schema of the response body
{
"allOf": [
{
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"description": "Either specific error code in case of invalid request or http status code",
"type": "number",
"example": 404
},
"message": {
"description": "Message describing error",
"type": "string"
},
"stacktraces": {
"description": "Optional stacktraces, sent when node is in debug mode",
"type": "array",
"items": {
"type": "string"
}
}
}
},
{
"example": {
"code": 400,
"message": "invalid block_hash argument"
}
}
]
}
Response 500 Internal Server Error
Schema of the response body
{
"type": "object",
"properties": {
"code": {
"description": "Either specific error code in case of invalid request or http status code",
"type": "number",
"example": 404
},
"message": {
"description": "Message describing error",
"type": "string"
},
"stacktraces": {
"description": "Optional stacktraces, sent when node is in debug mode",
"type": "array",
"items": {
"type": "string"
}
}
}
}
GET /relay/v1/data/bidtraces/builder_blocks_received¶
Get builder bid submissions.
Description
-
Returns a list of builder bids without execution payloads.
-
Only submissions that were successfully verified.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
block_hash |
query | string | No | A specific block hash. | |
block_number |
query | string | No | A specific block number. | |
builder_pubkey |
query | string | No | A specific builder public key. | |
limit |
query | string | No | The number of results. | |
slot |
query | string | No | A specific slot. |
Response 200 OK
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.
Schema of the response body
{
"type": "array",
"items": {
"allOf": [
{
"allOf": [
{
"type": "object",
"properties": {
"slot": {
"type": "string",
"example": "1"
},
"parent_hash": {
"type": "string",
"format": "hex",
"example": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"pattern": "^0x[a-fA-F0-9]{64}$"
},
"block_hash": {
"type": "string",
"format": "hex",
"example": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"pattern": "^0x[a-fA-F0-9]{64}$"
},
"builder_pubkey": {
"type": "string",
"format": "hex",
"pattern": "^0x[a-fA-F0-9]{96}$",
"description": "The validator's BLS public key, uniquely identifying them. _48-bytes, hex encoded with 0x prefix, case insensitive._",
"example": "0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a"
},
"proposer_pubkey": {
"type": "string",
"format": "hex",
"pattern": "^0x[a-fA-F0-9]{96}$",
"description": "The validator's BLS public key, uniquely identifying them. _48-bytes, hex encoded with 0x prefix, case insensitive._",
"example": "0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a"
},
"proposer_fee_recipient": {
"type": "string",
"format": "hex",
"description": "An address on the execution (Ethereum 1) network.",
"example": "0xAbcF8e0d4e9587369b2301D0790347320302cc09",
"pattern": "^0x[a-fA-F0-9]{40}$"
},
"gas_limit": {
"type": "string",
"example": "1"
},
"gas_used": {
"type": "string",
"example": "1"
},
"value": {
"type": "string",
"example": "1"
}
}
},
{
"type": "object",
"properties": {
"block_number": {
"type": "string",
"example": "1"
},
"num_tx": {
"type": "string",
"example": "1"
}
}
}
]
},
{
"type": "object",
"properties": {
"timestamp": {
"type": "string",
"example": "1"
},
"timestamp_ms": {
"type": "string",
"example": "1"
}
}
}
]
}
}
Response 400 Bad Request
Schema of the response body
{
"allOf": [
{
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"description": "Either specific error code in case of invalid request or http status code",
"type": "number",
"example": 404
},
"message": {
"description": "Message describing error",
"type": "string"
},
"stacktraces": {
"description": "Optional stacktraces, sent when node is in debug mode",
"type": "array",
"items": {
"type": "string"
}
}
}
},
{
"example": {
"code": 400,
"message": "cannot specify both slot and cursor"
}
}
]
}
Response 500 Internal Server Error
Schema of the response body
{
"type": "object",
"properties": {
"code": {
"description": "Either specific error code in case of invalid request or http status code",
"type": "number",
"example": 404
},
"message": {
"description": "Message describing error",
"type": "string"
},
"stacktraces": {
"description": "Optional stacktraces, sent when node is in debug mode",
"type": "array",
"items": {
"type": "string"
}
}
}
}
GET /relay/v1/data/validator_registration¶
Check that a validator is registered with the relay.
Description
-
Returns the latest validator registration for a given pubkey.
-
Useful to check whether your own registration was successful.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
pubkey |
query | string | No | The validator's public key. |
Response 200 OK
{
"message": {
"fee_recipient": "0xAbcF8e0d4e9587369b2301D0790347320302cc09",
"gas_limit": "1",
"timestamp": "1",
"pubkey": "0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a"
},
"signature": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505"
}
Schema of the response body
{
"type": "object",
"description": "The `SignedValidatorRegistration` object from the Builder API specification.",
"required": [
"message",
"signature"
],
"properties": {
"message": {
"type": "object",
"description": "The `ValidatorRegistration` object from the Builder API specification.",
"required": [
"fee_recipient",
"gas_limit",
"timestamp",
"pubkey"
],
"properties": {
"fee_recipient": {
"description": "Address to receive fees from the block.",
"type": "string",
"format": "hex",
"example": "0xAbcF8e0d4e9587369b2301D0790347320302cc09",
"pattern": "^0x[a-fA-F0-9]{40}$"
},
"gas_limit": {
"description": "Preferred gas limit of validator.",
"type": "string",
"example": "1"
},
"timestamp": {
"description": "Unix timestamp of registration.",
"type": "string",
"example": "1"
},
"pubkey": {
"description": "BLS public key of validator.",
"type": "string",
"format": "hex",
"pattern": "^0x[a-fA-F0-9]{96}$",
"example": "0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a"
}
}
},
"signature": {
"type": "string",
"format": "hex",
"pattern": "^0x[a-fA-F0-9]{192}$",
"example": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505"
}
}
}
Response 400 Bad Request
Schema of the response body
{
"allOf": [
{
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"description": "Either specific error code in case of invalid request or http status code",
"type": "number",
"example": 404
},
"message": {
"description": "Message describing error",
"type": "string"
},
"stacktraces": {
"description": "Optional stacktraces, sent when node is in debug mode",
"type": "array",
"items": {
"type": "string"
}
}
}
},
{
"example": {
"code": 400,
"message": "missing pubkey argument"
}
}
]
}
Response 500 Internal Server Error
Schema of the response body
{
"type": "object",
"properties": {
"code": {
"description": "Either specific error code in case of invalid request or http status code",
"type": "number",
"example": 404
},
"message": {
"description": "Message describing error",
"type": "string"
},
"stacktraces": {
"description": "Optional stacktraces, sent when node is in debug mode",
"type": "array",
"items": {
"type": "string"
}
}
}
}
Schemas¶
Bellatrix.SubmitBlockRequest¶
Type:
BidTraceV2¶
Type:
BidTraceV2WithTimestamp¶
Type:
Capella-ExecutionPayload¶
Type:
Capella-SubmitBlockRequest¶
Type:
Capella.SubmitBlockRequest¶
Type:
Deneb-ExecutionPayload¶
Type:
Deneb-SubmitBlockRequest¶
Type:
Deneb.SubmitBlockRequest¶
Type:
ExecutionPayload¶
Type:
SubmitBlockRequest¶
Type:
Tags¶
| Name | Description |
|---|---|
| Builder | Set of endpoints to interact with an external block builder. |
| Data | Set of endpoints to provide data about the relay. |