Add submit header optimistic endpoint

apis/relay/builder/headers.yaml

@@ -0,0 +1,66 @@
+post:
+  operationId: "submitHeader"
+  summary: Submit optimistic header to the relay.
+  description: |
+    * Headers 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
+      be `application/octet-stream`.
+
+    * To enable GZIP compression for the request body, the HTTP content encoding 
+      should be `gzip`. Compression is optional.
+
+    * The relay will check that the builder has enough collateral to cover the 
+      value of the bid. Otherwise the relay will not accept the optimistic header.
+
+    * The relay will need the rest of payload via the optimistic v2 endpoint. If 
+      not received in time, the relay will penalize the builder's collateral.
+
+    * 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.
+  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 header.
+    required: true
+    content:
+      application/json:
+        schema:
+          oneOf:
+            - $ref: "../../../relay-oapi.yaml#/components/schemas/Bellatrix.SubmitHeaderRequest"
+            - $ref: "../../../relay-oapi.yaml#/components/schemas/Capella.SubmitHeaderRequest"
+            - $ref: "../../../relay-oapi.yaml#/components/schemas/Deneb.SubmitHeaderRequest"
+        examples:
+          bellatrix:
+            $ref: "../../../relay-oapi.yaml#/components/examples/Bellatrix.SubmitHeaderRequest"
+          capella:
+            $ref: "../../../relay-oapi.yaml#/components/examples/Capella.SubmitHeaderRequest"
+          deneb:
+            $ref: "../../../relay-oapi.yaml#/components/examples/Deneb.SubmitHeaderRequest"
+      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"

examples/bellatrix/submit_header_request.json

@@ -0,0 +1,32 @@
+{
+  "value": {
+    "message": {
+      "slot": "1",
+      "parent_hash": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
+      "block_hash": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
+      "builder_pubkey": "0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a",
+      "proposer_fee_recipient": "0xabcf8e0d4e9587369b2301d0790347320302cc09",
+      "gas_limit": "1",
+      "gas_used": "1",
+      "value": "1"
+    },
+    "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"
+  }
+}

examples/capella/submit_header_request.json

@@ -0,0 +1,32 @@
+{
+  "value": {
+    "message": {
+      "slot": "1",
+      "parent_hash": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
+      "block_hash": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
+      "builder_pubkey": "0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a",
+      "proposer_fee_recipient": "0xabcf8e0d4e9587369b2301d0790347320302cc09",
+      "gas_limit": "1",
+      "gas_used": "1",
+      "value": "1"
+    },
+    "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",
+      "withdrawals_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2"
+    },
+    "signature": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505"
+  }
+}

examples/deneb/submit_header_request.json

@@ -0,0 +1,35 @@
+{
+  "value": {
+    "message": {
+      "slot": "1",
+      "parent_hash": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
+      "block_hash": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
+      "builder_pubkey": "0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a",
+      "proposer_fee_recipient": "0xabcf8e0d4e9587369b2301d0790347320302cc09",
+      "gas_limit": "1",
+      "gas_used": "1",
+      "value": "1"
+    },
+    "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",
+      "withdrawals_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2"
+    },
+    "blob_kzg_commitments": [
+      "0xa94170080872584e54a1cf092d845703b13907f2e6b3b1c0ad573b910530499e3bcd48c6378846b80d2bfa58c81cf3d5"
+    ],
+    "signature": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505"
+  }
+}

types/bellatrix/requests.yaml

@@ -14,3 +14,11 @@ Bellatrix:
         properties:
           execution_payload:
             $ref: "../../beacon-apis/types/bellatrix/execution_payload.yaml#/Bellatrix/ExecutionPayload"
+
+  SubmitHeaderRequest:
+    allOf:
+      - $ref: '#/Bellatrix/SubmitBlockRequestCommon'
+      - type: object
+        properties:
+          header:
+            $ref: "../../beacon-apis/types/bellatrix/execution_payload.yaml#/Bellatrix/ExecutionPayloadHeader"

types/capella/requests.yaml

@@ -6,3 +6,11 @@ Capella:
         properties:
           execution_payload:
             $ref: "../../beacon-apis/types/capella/execution_payload.yaml#/Capella/ExecutionPayload"
+
+  SubmitHeaderRequest:
+    allOf:
+      - $ref: '#/Bellatrix/SubmitBlockRequestCommon'
+      - type: object
+        properties:
+          header:
+            $ref: "../../beacon-apis/types/bellatrix/execution_payload.yaml#/Capella/ExecutionPayloadHeader"

types/deneb/requests.yaml

@@ -3,3 +3,17 @@ Deneb:
     allOf:
       - $ref: '../bellatrix/requests.yaml#/Bellatrix/SubmitBlockRequestCommon'
       - $ref: "../../builder-specs/types/deneb/execution_payload_and_blobs_bundle.yaml#/Deneb/ExecutionPayloadAndBlobsBundle"
+
+  SubmitHeaderRequest:
+    allOf:
+      - $ref: '#/Bellatrix/SubmitBlockRequestCommon'
+      - type: object
+        properties:
+          header:
+            $ref: "../../beacon-apis/types/bellatrix/execution_payload.yaml#/Deneb/ExecutionPayloadHeader"
+          blob_kzg_commitments:
+            type: array
+            items:
+              $ref: '../../beacon-apis/types/primitive.yaml#/KZGCommitment'
+            minItems: 0
+            maxItems: 4096

wordlist.txt

@@ -13,6 +13,7 @@ gzip
 http
 https
 json
+kzg
 mev
 nodejs
 npm