Update Beacon API for parity with Builder API and KeyManager API #630
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,56 @@ | ||
| post: | ||
| operationId: "submitBuilderPreferences" | ||
| summary: Submit builder preferences | ||
| description: | | ||
| Submits per-builder preferences for one or more proposers. The request body is a flat list of | ||
| `BuilderPreferencesEntry` objects, each naming the proposer in `proposer_pubkey`; the beacon | ||
| node submits each to the builder-API `submitBuilderPreferences` endpoint at the entry's `url`. | ||
| Applicable from the Gloas fork onwards. | ||
|
|
||
| Notes: | ||
| - Each entry targets one builder `url`, to which the beacon node makes one submission. | ||
| - Entries are identified by `proposer_pubkey`, so several proposers MAY submit to the same `url`. | ||
| - The beacon node routes each entry by its `url` and submits to that builder's | ||
| `submitBuilderPreferences` for the entry's `proposer_pubkey`, forwarding the `auth` and | ||
| `max_execution_payment`. | ||
| - Validators MAY submit in the epoch prior to proposing (from `state.proposer_lookahead`), so | ||
| builders hold the preferences before the bid request arrives. | ||
| parameters: | ||
| - in: header | ||
| schema: | ||
| $ref: "../../beacon-node-oapi.yaml#/components/schemas/ConsensusVersion" | ||
| required: true | ||
| name: Eth-Consensus-Version | ||
| description: "The active consensus version to which the submitted builder preferences belong." | ||
| tags: | ||
| - Validator | ||
| requestBody: | ||
| required: true | ||
| description: "Array of `BuilderPreferencesEntry` objects to submit, one per builder per proposer." | ||
| content: | ||
|
Member
There was a problem hiding this comment. this api is missing fork versioning, wouldn't it be good to keep the door open to easily update how to deal with this on the builder-api side can be different, but I would just add a fork version to leave the door open to add a new container in heze, there isn't much harm to add this metadata
Member
There was a problem hiding this comment.
@JasonVranek let's discussion the versioning here, so from my experience, using a in my opinion and this has worked quite nicely so far is to use the
Author
There was a problem hiding this comment.
yes I believe I'm doing this exactly, just to verify:
Member
There was a problem hiding this comment. yes sounds good to me, having |
||
| application/json: | ||
| schema: | ||
| type: array | ||
| maxItems: 4096 # MAX_BUILDER_ENTRIES * (MIN_SEED_LOOKAHEAD + 1) * SLOTS_PER_EPOCH | ||
| items: | ||
| $ref: "../../beacon-node-oapi.yaml#/components/schemas/Gloas.BuilderPreferencesEntry" | ||
| application/octet-stream: | ||
| schema: | ||
| description: "SSZ serialized `List[BuilderPreferencesEntry, MAX_BUILDER_ENTRIES * (MIN_SEED_LOOKAHEAD + 1) * SLOTS_PER_EPOCH]` bytes. Use Content-Type header to indicate that SSZ data is contained in the request body." | ||
| responses: | ||
| "200": | ||
| description: "Every entry was submitted and its builder accepted it" | ||
| "400": | ||
| description: | | ||
| One or more entries failed; the others were still submitted. Each failure is reported by the | ||
| entry's index via `IndexedErrorMessage`, proxying the builder's error for that entry. | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: "../../beacon-node-oapi.yaml#/components/schemas/IndexedErrorMessage" | ||
| "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" | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -224,6 +224,8 @@ paths: | |
| $ref: "./apis/validator/register_validator.yaml" | ||
| /eth/v1/validator/proposer_preferences: | ||
| $ref: "./apis/validator/proposer_preferences.yaml" | ||
| /eth/v1/validator/builder_preferences: | ||
| $ref: "./apis/validator/builder_preferences.yaml" | ||
| /eth/v1/validator/liveness/{epoch}: | ||
| $ref: "./apis/validator/liveness.yaml" | ||
| /eth/v1/validator/execution_payload_bids/{slot}/{builder_index}: | ||
|
|
@@ -493,6 +495,16 @@ components: | |
| $ref: "./types/fulu/data_column_sidecar.yaml#/Fulu/DataColumnSidecars" | ||
| Gloas.DataColumnSidecars: | ||
| $ref: "./types/gloas/data_column_sidecar.yaml#/Gloas/DataColumnSidecars" | ||
| Gloas.RequestAuth: | ||
| $ref: "./types/gloas/request_auth.yaml#/Gloas/RequestAuth" | ||
| Gloas.SignedRequestAuth: | ||
| $ref: "./types/gloas/request_auth.yaml#/Gloas/SignedRequestAuth" | ||
| Gloas.BuilderEntry: | ||
| $ref: "./types/gloas/builder_entry.yaml#/Gloas/BuilderEntry" | ||
| Gloas.BuilderConfig: | ||
| $ref: "./types/gloas/builder_entry.yaml#/Gloas/BuilderConfig" | ||
| Gloas.BuilderPreferencesEntry: | ||
| $ref: "./types/gloas/builder_preferences_entry.yaml#/Gloas/BuilderPreferencesEntry" | ||
| Node: | ||
| $ref: './types/fork_choice.yaml#/Node' | ||
| ExtraData: | ||
|
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
do we really need this header? if I understand correctly the sole purpose of this is so that the beacon node knows where to submit it via
submitSignedBeaconBlockbut the beacon node should know this anyways, since it got the bid from that builder via apithe only case where the beacon node doesn't know this is if it's a different node (eg. in a multi-node setup) if the primary node that sourced the bid from the builder via api went offline during the proposal flow but this seems like an edge case and even then, publishing only via p2p is a fine fallback behavior that is sufficient anyways most of the time
that said, we can keep the header if people wanna have it, just questionable to me if it's useful enough
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
this was solely for the multi-node support, not opinionated on it but it seemed like DVT teams wanted. Will leave for now and address most of the fat trimming comments
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I do not feel strongly about removing it, also I think when I commented there was in addition a
Eth-Proxy-Urlheader which is now gone, so this single header, if useful for DVT teams, might be worth keeping