Merge pull request #1 from chainbound/feat/relay-constraints

feat(relay): add bolt constraint APIs

apis/relay/builder/blocks_with_proofs.yaml

@@ -0,0 +1,56 @@
+post:
+  operationId: "submitBlockWithProofs"
+  summary: Submit a new block with inclusion proofs to the relay.
+  description: |
+    * This endpoint allows submitting blocks with inclusion proofs to the relay.
+    
+    * Blocks can be submitted in JSON or SSZ format, optionally GZIP encoded.
+    
+    * For JSON, the content type should be `application/json`. For SSZ, the content type should be `application/octet-stream`.
+    
+    * To enable GZIP compression, the HTTP content encoding should be `gzip`. Compression is optional.
+    
+    * The relay will verify the block's properties and the proposer payment in the transaction from builder to proposer `fee_recipient`.
+    
+    * The builder signature is over the SSZ encoded `message`.
+    
+    * The `message`, excluding transactions, will be made public via the data API, allowing verification of 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.
+  tags:
+    - Builder
+  parameters:
+    - name: cancellations
+      in: query
+      required: false
+      description: If set to 1, opt into bid cancellations.
+      schema:
+        $ref: "../../../relay-oapi.yaml#/components/schemas/Uint64"
+  requestBody:
+    description: A signed bid with an execution payload and inclusion proofs.
+    required: true
+    content:
+      application/json:
+        schema:
+          $ref: "../../../relay-oapi.yaml#/components/schemas/Deneb.SubmitBlockWithProofsRequest"
+        examples:
+          deneb:
+            $ref: "../../../relay-oapi.yaml#/components/examples/Deneb.SubmitBlockWithProofsRequest"
+      application/octet-stream:
+        schema:
+          description: "SSZ serialized request. Use content type header to indicate that SSZ data is contained in the request body."
+  responses:
+    "200":
+      description: Success response.
+    "400":
+      description: Error response.
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: "../../../relay-oapi.yaml#/components/schemas/ErrorMessage"
+              - example:
+                  code: 400
+                  message: "payload for this slot was already delivered"
+    "500":
+      $ref: "../../../relay-oapi.yaml#/components/responses/InternalError"

apis/relay/builder/constraints.yaml

@@ -0,0 +1,41 @@
+get:
+  operationId: "getConstraints"
+  summary: Get constraints stream from the relay.
+  description: |
+    * This endpoint allows fetching a stream of constraints from the relay.
+    
+    * The response is a stream of signed constraints, including messages and signatures.
+    
+    * The `backfill` parameter can be used to opt into backfilling constraints.
+    
+    * The headers `Content-Type` should be `text/event-stream` and `Connection` should be `keep-alive`.
+  tags:
+    - Builder
+  parameters:
+    - name: backfill
+      in: query
+      required: false
+      description: If set to true, opt into backfilling constraints.
+      schema:
+        type: boolean
+  headers:
+    Content-Type:
+      schema:
+        type: string
+        example: "text/event-stream"
+    Connection:
+      schema:
+        type: string
+        example: "keep-alive"
+  requestBody:
+    description: Empty request body.
+    required: false
+  responses:
+    "200":
+      description: Stream of signed constraints.
+      content:
+        text/event-stream:
+          schema:
+            $ref: "../../../relay-oapi.yaml#/components/schemas/Deneb.SignedConstraints"
+    "500":
+      $ref: "../../../relay-oapi.yaml#/components/responses/InternalError"

examples/deneb/submit_block_with_proofs_request.json

@@ -0,0 +1,178 @@
+{
+  "value": {
+    "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"
+          }
+        },
+        "signature": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505"
+      }
+    },
+    "proof": {
+      "indexes": [1],
+      "transaction_hashes": [
+        "b190c3b9978f9bb065fa841358745bb05f1a26ba5b455ac10161ba066e4b2999"
+      ],
+      "merkle_hashes": [
+        [
+          "0x0000000000000000000000000000000000000000000000000000000000000000",
+          "0xf5a5fd42d16a20302798ef6ed309979b43003d2320d9f0e8ea9831a92759fb4b",
+          "0xdb56114e00fdd4c1f85c892bf35ac9a89289aaecb1ebd0a96cde606a748b5d71",
+          "0xc78009fdf07fc56a11f122370658a353aaa542ed63e44c4bc15ff4cd105ab33c",
+          "0x536d98837f2dd165a55d5eeae91485954472d56f246df256bf3cae19352a123c",
+          "0x9efde052aa15429fae05bad4d0b1d7c64da64d03d7a1854a588c2cb8430c0d30",
+          "0xd88ddfeed400a8755596b21942c1497e114c302e6118290f91e6772976041fa1",
+          "0x87eb0ddba57e35f6d286673802a4af5975e22506c7cf4c64bb6be5ee11527f2c",
+          "0x26846476fd5fc54a5d43385167c95144f2643f533cc85bb9d16b782f8d7db193",
+          "0x506d86582d252405b840018792cad2bf1259f1ef5aa5f887e13cb2f0094f51e1",
+          "0xffff0ad7e659772f9534c195c815efc4014ef1e1daed4404c06385d11192e92b",
+          "0x6cf04127db05441cd833107a52be852868890e4317e6a02ab47683aa75964220",
+          "0xb7d05f875f140027ef5118a2247bbb84ce8f2f0f1123623085daf7960c329f5f",
+          "0xdf6af5f5bbdb6be9ef8aa618e4bf8073960867171e29676f8b284dea6a08a85e",
+          "0xb58d900f5e182e3c50ef74969ea16c7726c549757cc23523c369587da7293784",
+          "0xd49a7502ffcfb0340b1d7885688500ca308161a7f96b62df9d083b71fcc8f2bb",
+          "0x8fe6b1689256c0d385f42f5bbe2027a22c1996e110ba97c171d3e5948de92beb",
+          "0x8d0d63c39ebade8509e0ae3c9c3876fb5fa112be18f905ecacfecb92057603ab",
+          "0x95eec8b2e541cad4e91de38385f2e046619f54496c2382cb6cacd5b98c26f5a4",
+          "0xf893e908917775b62bff23294dbbe3a1cd8e6cc1c35b4801887b646a6f81f17f",
+          "0x0100000000000000000000000000000000000000000000000000000000000000"
+        ]
+      ]
+    }
+  }
+}

relay-oapi.yaml

@@ -28,8 +28,12 @@ tags:
 paths:
   /relay/v1/builder/validators:
     $ref: "./apis/relay/builder/validators.yaml"
+  /relay/v1/builder/constraints:
+    $ref: "./apis/relay/builder/constraints.yaml"
   /relay/v1/builder/blocks:
     $ref: "./apis/relay/builder/blocks.yaml"
+  /relay/v1/builder/blocks_with_proofs:
+    $ref: "./apis/relay/builder/blocks_with_proofs.yaml"
   /relay/v1/data/bidtraces/proposer_payload_delivered:
     $ref: "./apis/relay/data/proposer_payload_delivered.yaml"
   /relay/v1/data/bidtraces/builder_blocks_received:
@@ -55,6 +59,10 @@ components:
       $ref: "./types/capella/requests.yaml#/Capella/SubmitBlockRequest"
     Deneb.SubmitBlockRequest:
       $ref: "./types/deneb/requests.yaml#/Deneb/SubmitBlockRequest"
+    Deneb.SubmitBlockWithProofsRequest:
+      $ref: "./types/deneb/proof_requests.yaml#/Deneb/SubmitBlockWithProofsRequest"
+    Deneb.SignedConstraints:
+      $ref: "./types/deneb/constraints.yaml#/Deneb/SignedConstraints"
     ValidatorsResponse:
       $ref: "./types/responses.yaml#/ValidatorsResponse"
     DeliveredPayloadsResponse:
@@ -73,3 +81,5 @@ components:
       $ref: "./examples/capella/submit_block_request.json"
     Deneb.SubmitBlockRequest:
       $ref: "./examples/deneb/submit_block_request.json"
+    Deneb.SubmitBlockWithProofsRequest:
+      $ref: "./examples/deneb/submit_block_with_proofs_request.json"

types/deneb/constraints.yaml

@@ -0,0 +1,39 @@
+Deneb:
+  SignedConstraints:
+      type: object
+      properties:
+        message:
+          $ref: "#/Deneb/ConstraintsMessage"
+        signature:
+          type: string
+          description: |
+            The ECDSA signature of the ConstraintsMessage object, encoded as bytes and
+            hashed with the keccak256 hash. The signature must come from the key-pair
+            associated with the proposer opted-in into Bolt.
+  ConstraintsMessage:
+    type: object
+    properties:
+      validator_index:
+        type: string
+        items:
+          $ref: "../../relay-oapi.yaml#/components/schemas/Uint64"
+      slot:
+        type: string
+        items:
+          $ref: "../../relay-oapi.yaml#/components/schemas/Uint64"
+      constraints:
+        type: array
+        items:
+          $ref: "#/Deneb/Constraint"
+  Constraint:
+    type: object
+    properties:
+      tx:
+        type: string
+        description: Transaction bytes.
+      index:
+        type: integer
+        items:
+          $ref: "../../relay-oapi.yaml#/components/schemas/Uint64"
+        nullable: true
+        description: Position index in the block.

types/deneb/proof_requests.yaml

@@ -0,0 +1,27 @@
+Deneb:
+  SubmitBlockWithProofsRequest:
+    allOf:
+      - $ref: './requests.yaml#/Deneb/SubmitBlockRequest'
+      - type: object
+        properties:
+          execution_payload:
+            $ref: "../../beacon-apis/types/bellatrix/execution_payload.yaml#/Bellatrix/ExecutionPayload"
+
+  InclusionProof:
+    type: object
+    properties:
+      transaction_hashes:
+        type: array
+        items:
+          $ref: "../../beacon-apis/types/primitive.yaml#/Bytes32"
+        maxItems: 256
+      generalized_indexes:
+        type: array
+        items:
+          $ref: "../../beacon-apis/types/primitive.yaml#/Uint64"
+        maxItems: 256
+      merkle_hashes:
+        type: array
+        items:
+          type: array
+        maxItems: 256