Skip to main content

Constraints API: Relay

Overview​

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

  • Getter function for delegations and constraints in a slot.
  • Subscription to new constraints using Server Side Events (SSE).
  • Implement an updated block submission endpoint with support for inclusion proofs.

relay namespace​

/relay/v1/builder/delegations?slot={slot}​

Return the active delegations for the proposer of this slot, if it exists.

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

Schema

# A signed delegation
class SignedDelegation(Container):
    message: Delegation
    signature: BLSSignature

# A delegation from a proposer to a BLS public key
class Delegation(Container):
    action: uint8, # must be 0 for all delegations
    validator_pubkey: BLSPubkey,
    delegatee_pubkey: BLSPubkey

Description

This endpoint returns the active delegations for the validator scheduled to propose at the provided slot. If no such delegations exists, the endpoint should return an empty list. In that case, the validator key will be the only valid constraint signing key.

Example body
[
  {
    "message": {
      "action": 0,
      "validator_pubkey": "0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a",
      "delegatee_pubkey": "0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a"
    },
    "signature": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505"
  },
  ....
]

/relay/v1/builder/constraints?slot={slot}​

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):
    pubkey: 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.

Example body
[
  {
  "message": {
      "pubkey": "0xa695ad325dfc7e1191fbc9f186f58eff42a634029731b18380ff89bf42c464a42cb8ca55b200f051f57f1e1893c68759",
      "slot": 32,
      "top": false,
      "transactions": [
      "0x02f86c870c72dd9d5e883e4d0183408f2382520894d2e2adf7177b7a8afddbc12d1634cf23ea1a71020180c001a08556dcfea479b34675db3fe08e29486fe719c2b22f6b0c1741ecbbdce4575cc6a01cd48009ccafd6b9f1290bbe2ceea268f94101d1d322c787018423ebcbc87ab4",
      "0x02f86c870c72dd9d5e883e4d0183408f2382520894d2e2adf7177b7a8afddbc12d1634cf23ea1a71020180c001a08556dcfea479b34675db3fe08e29486fe719c2b22f6b0c1741ecbbdce4575cc6a01cd48009ccafd6b9f1290bbe2ceea268f94101d1d322c787018423ebcbc87ab4"
      ]
  },
  "signature": "0xae5aa93391a256eebef79fe452951ae196b3b3ac9046e45cd63713a57ad0548ddb56430477cb3d70287710984fc4bc4e091da1d5594de25c2caeca4872b35c12587ef168b0c878cde4025d66d4195cd875df7e2c4d7ba2b9fe2010b0cf5caccc"
  },
  {
    "message": {
      "pubkey": "0xa695ad325dfc7e1191fbc9f186f58eff42a634029731b18380ff89bf42c464a42cb8ca55b200f051f57f1e1893c68759",
      "slot": 33,
      "top": false,
      "transactions": [
        "0x02f86c870c72dd9d5e883e4d0183408f2382520894d2e2adf7177b7a8afddbc12d1634cf23ea1a71020180c001a08556dcfea479b34675db3fe08e29486fe719c2b22f6b0c1741ecbbdce4575cc6a01cd48009ccafd6b9f1290bbe2ceea268f94101d1d322c787018423ebcbc87ab4",
        "0x02f86c870c72dd9d5e883e4d0183408f2382520894d2e2adf7177b7a8afddbc12d1634cf23ea1a71020180c001a08556dcfea479b34675db3fe08e29486fe719c2b22f6b0c1741ecbbdce4575cc6a01cd48009ccafd6b9f1290bbe2ceea268f94101d1d322c787018423ebcbc87ab4"
      ]
    },
    "signature": "0x9822741e08975fffdd16ba39967f86780b6b11c5235bde3f4d68c7ef8612ae5d1e71cd40431baa74e699e4f94e3090300c00bef720e8b982e12e7e9eb9cc78ab75ed99e412c99ea4ea89cc887ab7849b0fc9e299183f977965c0607b5a178793"
  }
]

/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):
    pubkey: BLSPubkey,
    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_indexes: 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",
              "pubkey": "0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a"
            },
            "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_indexes": [1],
        "merkle_hashes": [
          [
            "0x0000000000000000000000000000000000000000000000000000000000000000",
            "0xf5a5fd42d16a20302798ef6ed309979b43003d2320d9f0e8ea9831a92759fb4b"
          ]
        ]
      },
      "signature": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505"
    }
  }
}