Constraints API: Relay

• Original API docs: https://flashbots.github.io/relay-specs
• Updated API docs: https://chainbound.github.io/relay-specs

Overview

The Relay API is the way for block builders to communicate bids to relays in the PBS pipeline. New responsibilities:

• Subscription to new constraints using Server Side Events (SSE)
• Implement an updated block submission endpoint with support for inclusion proofs

Endpoints

relay namespace

/relay/v1/builder/constraints

Returns all constraints for a given slot.

• Method: GET
• Parameters: slot: uint64 (query)
• Body: Empty
• Response: JSON object of type List[SignedConstraints]:

Schema

class SignedConstraints(Container):
    message: ConstraintsMessage
    signature: BLSSignature

class ConstraintsMessage(Container):
    validator_index: uint64,
    slot: uint64
    top: boolean,
    transactions: List[Bytes, MAX_CONSTRAINTS_PER_SLOT]

Description

This endpoint returns all of the valid constraints for a given slot. Builders can use it at startup to backfill any missing data. After that, it is recommended to subscribe to the stream.

/relay/v1/builder/constraints_stream

Returns an SSE stream of constraints.

• Method: GET
• Parameters: Empty
• Headers:
  • Content-Type: text/event-stream
  • Connection: keep-alive
• Body: Empty
• Response: stream of JSON objects of type List[SignedConstraints]:

Schema

class SignedConstraints(Container):
    message: ConstraintsMessage
    signature: BLSSignature

class ConstraintsMessage(Container):
    validator_index: uint64,
    slot: uint64
    top: boolean,
    transactions: List[Bytes, MAX_CONSTRAINTS_PER_SLOT]

Description

This stream pushes batched constraints from relays to builders, without the need for builders to continually use the poll endpoint described above. This stream will yield an event every time proposers submit constraints to the relay. In practice, proposers are only expected to submit constraints at their configured submission deadline.

/relay/v1/builder/blocks_with_proofs

Endpoint for submitting blocks with inclusion proofs.

• Method: POST
• Parameters: cancellations: bool (query)
• Body: of type VersionedSubmitBlockRequestWithProofs
• Response: Empty

Schema

class VersionedSubmitBlockRequestWithProofs(Container):
  ... # All regular fields from VersionedSubmitBlockRequest, additionally
  proofs: InclusionProofs

class InclusionProofs(Container):
  transanction_hashes: List[Bytes32, MAX_CONSTRAINTS_PER_SLOT]
  generalized_indeces: List[uint64, MAX_CONSTRAINTS_PER_SLOT]
  merkle_hashes: List[List[Bytes32], MAX_CONSTRAINTS_PER_SLOT]

Description

VersionedSubmitBlockRequest is from the original specs. VersionedSubmitBlockRequestWithProofs just adds proofs of inclusion. Note that InclusionProofs is a Merkle multiproof, as defined in the consensus specs.

Example body

{
  "inner": {
    "message": {
      "slot": "1",
      "proposer_index": "1",
      "parent_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
      "state_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
      "body": {
        "randao_reveal": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505",
        "eth1_data": {
          "deposit_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
          "deposit_count": "1",
          "block_hash": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2"
        },
        "graffiti": "0xdeadbeefc0ffeedeadbeefc0ffeedeadbeefc0ffeedeadbeefc0ffeedeadbeef",
        "proposer_slashings": [
          {
            "signed_header_1": {
              "message": {
                "slot": "1",
                "proposer_index": "1",
                "parent_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
                "state_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
                "body_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2"
              },
              "signature": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505"
            },
            "signed_header_2": {
              "message": {
                "slot": "1",
                "proposer_index": "1",
                "parent_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
                "state_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
                "body_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2"
              },
              "signature": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505"
            }
          }
        ],
        "attester_slashings": [
          {
            "attestation_1": {
              "attesting_indices": ["1"],
              "signature": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505",
              "data": {
                "slot": "1",
                "index": "1",
                "beacon_block_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
                "source": {
                  "epoch": "1",
                  "root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2"
                },
                "target": {
                  "epoch": "1",
                  "root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2"
                }
              }
            },
            "attestation_2": {
              "attesting_indices": ["1"],
              "signature": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505",
              "data": {
                "slot": "1",
                "index": "1",
                "beacon_block_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
                "source": {
                  "epoch": "1",
                  "root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2"
                },
                "target": {
                  "epoch": "1",
                  "root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2"
                }
              }
            }
          }
        ],
        "attestations": [
          {
            "aggregation_bits": "0x01",
            "signature": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505",
            "data": {
              "slot": "1",
              "index": "1",
              "beacon_block_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
              "source": {
                "epoch": "1",
                "root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2"
              },
              "target": {
                "epoch": "1",
                "root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2"
              }
            }
          }
        ],
        "deposits": [
          {
            "proof": [
              "0xeeffb6c21a01d3abf09cd6c56e5d48f5ea0fc3bb0de906e3beea3e73776329cb",
              "0x601c3b24a99d023224d50811bed19449890febb719a31d09ac414c4632f3c0ba"
              ...
            ],
            "data": {
              "pubkey": "0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a",
              "withdrawal_credentials": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
              "amount": "1",
              "signature": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505"
            }
          }
        ],
        "voluntary_exits": [
          {
            "message": {
              "epoch": "1",
              "validator_index": "1"
            },
            "signature": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505"
          }
        ],
        "sync_aggregate": {
          "sync_committee_bits": "0x01",
          "sync_committee_signature": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505"
        },
        "execution_payload_header": {
          "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_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2"
        }
      },
      "proofs": {
        "transaction_hashes": [
          "b190c3b9978f9bb065fa841358745bb05f1a26ba5b455ac10161ba066e4b2999"
        ],
        "generalized_indeces": [1],
        "merkle_hashes": [
          [
            "0x0000000000000000000000000000000000000000000000000000000000000000",
            "0xf5a5fd42d16a20302798ef6ed309979b43003d2320d9f0e8ea9831a92759fb4b"
          ]
        ]
      },
      "signature": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505"
    }
  }
}