Add produceBlockV4WithBid

CHANGES.md

@@ -8,6 +8,7 @@ There are likely to be descriptions etc outside of the list below, but new query
 
 | Endpoint                                                                                                            | [Lighthouse](https://github.com/sigp/lighthouse) | [Lodestar](https://github.com/ChainSafe/lodestar) | [Nimbus](https://github.com/status-im/nimbus-eth2) | [Prysm](https://github.com/prysmaticlabs/prysm) | [Teku](https://github.com/ConsenSys/teku) |
 |---------------------------------------------------------------------------------------------------------------------|--------------------------------------------------|---------------------------------------------------|----------------------------------------------------|-------------------------------------------------|-------------------------------------------|
+| [#627](https://github.com/ethereum/beacon-APIs/pull/627) `POST /eth/v4/validator/blocks/{slot}/with_bid` added                                |                                                  |                                                  |                                                    |                                                 |                                           |
 | [#580](https://github.com/ethereum/beacon-APIs/pull/580) / [#624](https://github.com/ethereum/beacon-APIs/pull/624) `GET /eth/v4/validator/blocks/{slot}` added         |                                                  |                                                  |                                                    |                                                 |                                           |
 | [#552](https://github.com/ethereum/beacon-APIs/pull/552) `GET /eth/v1/validator/execution_payload_bids/{slot}/{builder_index}` added         |                                                  |                                                  |                                                    |                                                 |                                           |
 | [#580](https://github.com/ethereum/beacon-APIs/pull/580) / [#624](https://github.com/ethereum/beacon-APIs/pull/624) `GET /eth/v1/validator/execution_payload_envelopes/{slot}/{beacon_block_root}` added         |                                                  |                                                  |                                                    |                                                 |                                           |

apis/validator/block.v4_with_bid.yaml

@@ -0,0 +1,175 @@
+post:
+  tags:
+    - Validator
+    - ValidatorRequiredApi
+  operationId: "produceBlockV4WithBid"
+  summary: "Produce a new block with best-effort inclusion of a supplied execution payload bid, without signature."
+  description: |
+    Requests a beacon node to produce a valid block with best-effort inclusion of the supplied
+    signed execution payload bid, which can then be signed by a validator.
+
+    The beacon node MAY replace the supplied bid when its circuit breaker mechanism is active or
+    when the supplied bid is invalid. If the supplied bid is well-formed but fails validation,
+    the beacon node MUST continue block production using another viable bid or a local execution
+    payload.
+
+    Post-Gloas, proposers submit execution payload bids rather than full execution payloads,
+    so there is no longer a concept of blinded or unblinded blocks. Builders release the
+    payload later. This endpoint is specific to the post-Gloas forks and is not backwards compatible
+    with previous forks.
+
+    When self-building (local execution payload), the response will include the full block contents
+    including the beacon block, execution payload envelope, blobs, and KZG proofs.
+    When using the supplied external builder bid, only the `BeaconBlock` is returned as the beacon
+    node does not have access to the builder's execution payload.
+
+    The `Eth-Execution-Payload-Included` header and `execution_payload_included` response field
+    indicate which response type was returned.
+  parameters:
+    - name: slot
+      in: path
+      required: true
+      description: "The slot for which the block should be proposed."
+      schema:
+        $ref: "../../beacon-node-oapi.yaml#/components/schemas/Uint64"
+    - name: randao_reveal
+      in: query
+      required: true
+      description: "The validator's randao reveal value."
+      schema:
+        $ref: '../../beacon-node-oapi.yaml#/components/schemas/Signature'
+    - name: graffiti
+      in: query
+      required: false
+      description: "Arbitrary data validator wants to include in block."
+      schema:
+        $ref: '../../beacon-node-oapi.yaml#/components/schemas/Graffiti'
+    - name: skip_randao_verification
+      $ref: '../../beacon-node-oapi.yaml#/components/parameters/SkipRandaoVerification'
+    - name: include_payload
+      in: query
+      required: false
+      description: |
+        Controls whether the execution payload envelope and blobs are included in the response
+        when self-building (using local execution payload).
+
+        When `true` (default), the response includes the full block contents: beacon block,
+        execution payload envelope, blobs, and KZG proofs. This enables stateless operation
+        where the validator client can use multiple beacon nodes (multi-BN setups, distributed validators, failover).
+
+        When `false`, only the beacon block is returned and the beacon node caches the execution
+        payload envelope and blobs internally. The validator client must then fetch them separately
+        via `GET /eth/v1/validator/execution_payload_envelopes/{slot}/{beacon_block_root}`. This saves
+        bandwidth but requires the validator client to publish via the same beacon node that
+        produced the block (stateful operation).
+
+        This parameter only affects self-building scenarios. When using the supplied external
+        builder bid, only the beacon block is returned regardless of this parameter (the beacon
+        node does not have access to the builder's execution payload).
+      schema:
+        type: boolean
+        default: true
+    - name: builder_boost_factor
+      in: query
+      required: false
+      description: |
+        Percentage multiplier to apply to the builder bid's value when choosing between that bid
+        and a payload from the paired execution node. The beacon node SHOULD use the supplied
+        `SignedExecutionPayloadBid` when it is valid, but MAY replace an invalid supplied bid with
+        another viable bid. This parameter is only relevant if a viable bid is available and the
+        beacon node receives a valid response from the paired execution node. When these
+        preconditions are met, the server MUST act as follows:
+
+        * if `exec_node_payload_value >= builder_boost_factor * (builder_payload_value // 100)`,
+          then return a block committing to the local execution node payload (with the payload
+          itself included if `include_payload` is set to true).
+        * otherwise, return a block committing to the selected builder bid (without execution
+          payload, as it is not yet available).
+
+        Servers must support the following values of the boost factor which encode common
+        preferences:
+
+        * `builder_boost_factor=0`: prefer the local execution node payload unless an error makes
+          it unviable.
+        * `builder_boost_factor=100`: profit maximization mode; choose whichever payload pays
+          more.
+        * `builder_boost_factor=2**64 - 1`: prefer the selected builder bid unless an error or
+          beacon node health check makes it unviable.
+
+        Servers should use saturating arithmetic or another technique to ensure that large values
+        of the `builder_boost_factor` do not trigger overflows or errors. If no viable bid is
+        available, the beacon node MUST respond with a block committing to the local execution
+        node payload, which the caller can choose to reject if it wishes. If the value is provided
+        but out of range for a 64-bit unsigned integer, then an error response with status code 400
+        MUST be returned.
+      schema:
+        $ref: "../../beacon-node-oapi.yaml#/components/schemas/Uint64"
+  requestBody:
+    description: "The `SignedExecutionPayloadBid` to consider for best-effort inclusion in the block."
+    required: true
+    content:
+      application/json:
+        schema:
+          $ref: "../../beacon-node-oapi.yaml#/components/schemas/Gloas.SignedExecutionPayloadBid"
+      application/octet-stream:
+        schema:
+          description: "SSZ serialized `SignedExecutionPayloadBid` bytes. Use Content-Type header to specify this format."
+  responses:
+    "200":
+      description: Success response
+      headers:
+        Eth-Consensus-Version:
+          $ref: '../../beacon-node-oapi.yaml#/components/headers/Eth-Consensus-Version'
+        Eth-Consensus-Block-Value:
+          $ref: '../../beacon-node-oapi.yaml#/components/headers/Eth-Consensus-Block-Value'
+        Eth-Execution-Payload-Included:
+          $ref: '../../beacon-node-oapi.yaml#/components/headers/Eth-Execution-Payload-Included'
+      content:
+        application/json:
+          schema:
+            title: "ProduceBlockV4WithBidResponse"
+            type: object
+            required: [version, consensus_block_value, execution_payload_included, data]
+            properties:
+              version:
+                type: string
+                enum: [gloas]
+                example: "gloas"
+              consensus_block_value:
+                type: string
+                example: "12345"
+                description: "Consensus rewards for this block in Wei"
+              execution_payload_included:
+                type: boolean
+                description: |
+                  Indicates whether the execution payload envelope is included in the response.
+                  When `true`, the `data` field contains the full
+                  execution payload envelope, blobs, and KZG proofs. When `false`, the `data`
+                  field contains only a `BeaconBlock`.
+                example: false
+              data:
+                anyOf:
+                  - $ref: "../../beacon-node-oapi.yaml#/components/schemas/Gloas.BeaconBlock"
+                  - $ref: "../../beacon-node-oapi.yaml#/components/schemas/Gloas.BlockContents"
+        application/octet-stream:
+          schema:
+            description: "SSZ serialized `BeaconBlock` or `BlockContents` bytes. Use Accept header to choose this response type, version string is sent in header `Eth-Consensus-Version` and payload inclusion indicated by `Eth-Execution-Payload-Included` header."
+    "400":
+      description: "Invalid block production request"
+      content:
+        application/json:
+          schema:
+            $ref: "../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage"
+          examples:
+            InvalidRequest:
+              value:
+                code: 400
+                message: "Invalid request to produce a block"
+    "406":
+      $ref: "../../beacon-node-oapi.yaml#/components/responses/NotAcceptable"
+    "415":
+      $ref: "../../beacon-node-oapi.yaml#/components/responses/UnsupportedMediaType"
+    "500":
+      $ref: '../../beacon-node-oapi.yaml#/components/responses/InternalError'
+    "503":
+      $ref: '../../beacon-node-oapi.yaml#/components/responses/CurrentlySyncing'

beacon-node-oapi.yaml

@@ -198,6 +198,8 @@ paths:
     $ref: "./apis/validator/block.v3.yaml"
   /eth/v4/validator/blocks/{slot}:
     $ref: "./apis/validator/block.v4.yaml"
+  /eth/v4/validator/blocks/{slot}/with_bid:
+    $ref: "./apis/validator/block.v4_with_bid.yaml"
   /eth/v1/validator/attestation_data:
     $ref: "./apis/validator/attestation_data.yaml"
   /eth/v1/validator/payload_attestation_data:

validator-flow.md

@@ -23,6 +23,10 @@ If proposing block, then at immediate start of slot:
      - `include_payload=false`: returns only the `BeaconBlock`. The beacon node caches the execution payload
        envelope and blobs internally (stateful operation, must publish via the same beacon node).
      - When using an external builder's bid, only the `BeaconBlock` is returned regardless of `include_payload`.
+     - A validator client that already has a signed execution payload bid can instead use
+         [produceBlockV4WithBid](#/Validator/produceBlockV4WithBid). Inclusion is best effort: the
+         beacon node may replace the supplied bid when it is invalid or when its circuit breaker
+         mechanism is active.
 2. Sign block
 3. [Submit SignedBeaconBlock](#/ValidatorRequiredApi/publishBlock) (BeaconBlock + signature)
 4. Post-Gloas, if self-building (proposer's own bid included in block):