Add bid proofs to the builder bid response

apis/builder/header.v2.yaml

@@ -0,0 +1,78 @@
+get:
+  operationId: "getHeaderV2"
+  summary: Get an execution payload header along with the payout proof to the bid
+  description: |
+    Requests a builder node to produce a valid execution payload header, which
+    can be integrated into a blinded beacon block and signed.
+
+    Builder must immediately return the header that is able to pay the
+    proposer's registered `fee_recipient` the most. If the builder is unaware
+    of `parent_hash`, it must error. If `pubkey` does not match the builder's
+    expected proposer `pubkey` for `slot`, it must error. If the builder has
+    not received a validator registration associated with `pubkey`, it must
+    error.
+
+    When possible, the builder must return a header with `gas_limit` equal to
+    proposer's registered value. If this isn't possible due to the large
+    difference between `parent.gas_limit` and the preferred `gas_limit`, the
+    builder must return a header that moves `gas_limit` the maximum amount
+    allowed under the rules of consensus (currently `parent.gas_limit +/-
+    parent.gas_limit / 1024`).
+  tags:
+    - Builder
+  parameters:
+    - name: slot
+      in: path
+      required: true
+      description: The slot for which the block should be proposed.
+      schema:
+        $ref: "../../builder-oapi.yaml#/components/schemas/Uint64"
+    - name: parent_hash
+      in: path
+      required: true
+      description: Hash of execution layer block the proposer will build on.
+      schema:
+        $ref: "../../builder-oapi.yaml#/components/schemas/Root"
+    - name: pubkey
+      in: path
+      required: true
+      description: The validator's BLS public key.
+      schema:
+        $ref: "../../builder-oapi.yaml#/components/schemas/Pubkey"
+  responses:
+    "200":
+      description: Success response.
+      content:
+        application/json:
+          schema:
+            title: GetHeaderResponse
+            type: object
+            properties:
+              version:
+                type: string
+                enum: [ bellatrix ]
+                example: "bellatrix"
+              data:
+                oneOf:
+                 - $ref: "../../builder-oapi.yaml#/components/schemas/Bellatrix.SignedBuilderBidV2"
+              proof:
+                oneOf:
+                - $ref: "../../builder-oapi.yaml#/components/schemas/BidProof"
+          examples:
+            bellatrix:
+              $ref: "../../builder-oapi.yaml#/components/examples/Bellatrix.SignedBuilderBidV2"
+    "204":
+      description: No header is available.
+    "400":
+      description: Error response.
+      content:
+        application/json:
+          schema:
+            $ref: "../../builder-oapi.yaml#/components/schemas/ErrorMessage"
+          examples:
+            InvalidRequest:
+              value:
+                code: 400
+                message: "Unknown hash: missing parent hash"
+    "500":
+      $ref: "../../builder-oapi.yaml#/components/responses/InternalError"

apis/builder/header.yaml

@@ -18,6 +18,7 @@ get:
     builder must return a header that moves `gas_limit` the maximum amount
     allowed under the rules of consensus (currently `parent.gas_limit +/-
     parent.gas_limit / 1024`).
+  deprecated: true
   tags:
     - Builder
   parameters:

examples/bellatrix/signed_builder_bid_v2.json

@@ -0,0 +1,29 @@
+{
+  "value": {
+    "version": "bellatrix",
+    "data": {
+      "message": {
+        "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"
+        },
+        "value": "1",
+        "pubkey": "0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a",
+         "fee_recipient": "0xabcf8e0d4e9587369b2301d0790347320302cc09",
+      },
+      "signature": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505"
+    }
+  }
+}

specs/builder.md

@@ -31,6 +31,13 @@
 | - | - |
 | `DOMAIN_APPLICATION_BUILDER` | `DomainType('0x00000001')` |
 
+### Execution proof
+
+| Name | Value |
+| - | - |
+| `MAX_EXECUTION_PROOF_DEPTH` | 64 |
+| `MAX_BRANCH_SIZE` | `17` |
+
 ## Containers
 
 Consider the following definitions supplementary to the definitions in
@@ -72,10 +79,13 @@ Bellatrix).
 ##### `BuilderBid`
 
 ```python
-class BuilderBid(Container):
+class BuilderBidV2(Container):
     header: ExecutionPayloadHeader
     value: uint256
     pubkey: BLSPubkey
+    fee_recipient: ExecutionAddress
+    # RLP encoded size of list of max 17 32bytes branches is 564 bytes
+    proof: List[ByteList[564], MAX_EXECUTION_PROOF_DEPTH] 
 ```
 
 ##### `SignedBuilderBid`

types/bellatrix/bid.v2.yaml

@@ -0,0 +1,27 @@
+Bellatrix:
+  BuilderBidV2:
+    type: object
+    description: "The `BuilderBidV2` object from the Builder API spec."
+    properties:
+      header:
+        $ref: "../../beacon-apis/types/bellatrix/execution_payload.yaml#/Bellatrix/ExecutionPayloadHeader"
+        description: "`ExecutionPayloadHeader` to use in block proposal."
+      value:
+        $ref: "../../beacon-apis/types/primitive.yaml#/Uint256"
+        description: "Payment in wei that will be paid to the `fee_recipient` account."
+      pubkey:
+        $ref: "../../beacon-apis/types/primitive.yaml#/Pubkey"
+        description: "BLS public key of builder."
+      # Builder should return where its paying out the bid to
+      fee_recipient:
+        $ref: '../../beacon-apis/types/primitive.yaml#/ExecutionAddress'
+        description: "The address the bid will be paid to, as registered previously with builder"
+
+  SignedBuilderBidV2:
+    type: object
+    description: "The `SignedBuilderBidV2` object from the Builder API spec."
+    properties:
+      message:
+        $ref: "#/Bellatrix/BuilderBidV2"
+      signature:
+        $ref: "../../beacon-apis/types/primitive.yaml#/Signature"

types/proof.yaml

@@ -0,0 +1,26 @@
+ProofNode:
+  type: string
+  description: "An rlp encoded hex string representing a node in merkle proof branch"
+  example: "0xdf820023db808080c620841920682380c4208219208080808080808080808080"
+  # RLP encoded size of list of max 17 32bytes branches is 564 bytes
+  pattern: "^0x[a-fA-F0-9]{0,1128}$"
+
+ProofNodes:
+  type: array
+  items:
+    allOf:
+      - $ref: "#/ProofNode"
+  maxItems: 64
+
+BidProof:
+  type: object
+  description: "The merkle proof of the `fee_recipient` account post the corresponding `BuilderBidV2` promised payout"
+  properties:
+    address:
+      $ref: '../../beacon-apis/types/primitive.yaml#/ExecutionAddress'
+      description: "The account address for which proof has been generated, should match `fee_recipient` of `BuilderBidV2`"
+    balance:
+      $ref: "../../beacon-apis/types/primitive.yaml#/Uint256"
+      description: "Post balance in gwei of the account (corresponding to the `stateRoot` of the `header` returned by `BuilderBidV2`)"
+    nodes:
+      $ref: "#/ProofNodes"