From bb60e92b39c8e8aa54a66244a4598a08c808ce76 Mon Sep 17 00:00:00 2001 From: Nico Flaig Date: Wed, 11 Sep 2024 01:55:17 +0100 Subject: [PATCH 1/7] Clarify server behavior if content type is not supported (#457) Co-authored-by: Paul Harris --- apis/beacon/blob_sidecars/blob_sidecars.yaml | 2 ++ apis/beacon/blocks/blinded_block.yaml | 2 ++ apis/beacon/blocks/block.v2.yaml | 3 ++- apis/beacon/deposit_snapshot.yaml | 4 ++- apis/beacon/light_client/bootstrap.yaml | 9 +------ apis/beacon/light_client/finality_update.yaml | 9 +------ .../light_client/optimistic_update.yaml | 9 +------ apis/beacon/light_client/updates.yaml | 9 +------ apis/builder/states/expected_withdrawals.yaml | 2 ++ apis/debug/state.v2.yaml | 2 ++ apis/validator/blinded_block.yaml | 2 ++ apis/validator/block.v2.yaml | 2 ++ apis/validator/block.v3.yaml | 2 ++ beacon-node-oapi.yaml | 14 +++++++--- types/http.yaml | 27 +++++++++++++++++-- 15 files changed, 59 insertions(+), 39 deletions(-) diff --git a/apis/beacon/blob_sidecars/blob_sidecars.yaml b/apis/beacon/blob_sidecars/blob_sidecars.yaml index 40321774..92b4e853 100644 --- a/apis/beacon/blob_sidecars/blob_sidecars.yaml +++ b/apis/beacon/blob_sidecars/blob_sidecars.yaml @@ -68,5 +68,7 @@ get: example: code: 404 message: "Block not found" + "406": + $ref: "../../../beacon-node-oapi.yaml#/components/responses/NotAcceptable" "500": $ref: "../../../beacon-node-oapi.yaml#/components/responses/InternalError" diff --git a/apis/beacon/blocks/blinded_block.yaml b/apis/beacon/blocks/blinded_block.yaml index 35e89e7a..d85bce32 100644 --- a/apis/beacon/blocks/blinded_block.yaml +++ b/apis/beacon/blocks/blinded_block.yaml @@ -60,5 +60,7 @@ get: example: code: 404 message: "Block not found" + "406": + $ref: "../../../beacon-node-oapi.yaml#/components/responses/NotAcceptable" "500": $ref: "../../../beacon-node-oapi.yaml#/components/responses/InternalError" diff --git a/apis/beacon/blocks/block.v2.yaml b/apis/beacon/blocks/block.v2.yaml index f1ef818d..9f2322de 100644 --- a/apis/beacon/blocks/block.v2.yaml +++ b/apis/beacon/blocks/block.v2.yaml @@ -41,7 +41,6 @@ get: - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Deneb.SignedBeaconBlock" application/octet-stream: schema: - description: "SSZ serialized block bytes. Use Accept header to choose this response type" "400": description: "The block ID supplied could not be parsed" @@ -61,5 +60,7 @@ get: example: code: 404 message: "Block not found" + "406": + $ref: "../../../beacon-node-oapi.yaml#/components/responses/NotAcceptable" "500": $ref: "../../../beacon-node-oapi.yaml#/components/responses/InternalError" diff --git a/apis/beacon/deposit_snapshot.yaml b/apis/beacon/deposit_snapshot.yaml index 67f26cda..b1c55062 100644 --- a/apis/beacon/deposit_snapshot.yaml +++ b/apis/beacon/deposit_snapshot.yaml @@ -3,7 +3,7 @@ summary: "Get Deposit Tree Snapshot" description: | Retrieve [EIP-4881](https://eips.ethereum.org/EIPS/eip-4881) Deposit Tree Snapshot. - Depending on `Accept` header it can be returned either as json or as bytes serialzed by SSZ + Depending on `Accept` header it can be returned either as json or as bytes serialized by SSZ tags: - Beacon responses: @@ -30,5 +30,7 @@ example: code: 404 message: "No Finalized Snapshot Available" + "406": + $ref: "../../beacon-node-oapi.yaml#/components/responses/NotAcceptable" "500": $ref: '../../beacon-node-oapi.yaml#/components/responses/InternalError' diff --git a/apis/beacon/light_client/bootstrap.yaml b/apis/beacon/light_client/bootstrap.yaml index 89b7f1fd..b535f088 100644 --- a/apis/beacon/light_client/bootstrap.yaml +++ b/apis/beacon/light_client/bootstrap.yaml @@ -54,13 +54,6 @@ get: code: 404 message: "LC bootstrap unavailable" "406": - description: Unacceptable media type - content: - application/json: - schema: - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage" - example: - code: 406 - message: "Accepted media type not supported" + $ref: "../../../beacon-node-oapi.yaml#/components/responses/NotAcceptable" "500": $ref: "../../../beacon-node-oapi.yaml#/components/responses/InternalError" diff --git a/apis/beacon/light_client/finality_update.yaml b/apis/beacon/light_client/finality_update.yaml index c1a395d3..298480d7 100644 --- a/apis/beacon/light_client/finality_update.yaml +++ b/apis/beacon/light_client/finality_update.yaml @@ -40,13 +40,6 @@ get: code: 404 message: "LC finality update unavailable" "406": - description: Unacceptable media type - content: - application/json: - schema: - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage" - example: - code: 406 - message: "Accepted media type not supported" + $ref: "../../../beacon-node-oapi.yaml#/components/responses/NotAcceptable" "500": $ref: "../../../beacon-node-oapi.yaml#/components/responses/InternalError" diff --git a/apis/beacon/light_client/optimistic_update.yaml b/apis/beacon/light_client/optimistic_update.yaml index dea560e5..16cb2208 100644 --- a/apis/beacon/light_client/optimistic_update.yaml +++ b/apis/beacon/light_client/optimistic_update.yaml @@ -40,13 +40,6 @@ get: code: 404 message: "LC optimistic update unavailable" "406": - description: Unacceptable media type - content: - application/json: - schema: - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage" - example: - code: 406 - message: "Accepted media type not supported" + $ref: "../../../beacon-node-oapi.yaml#/components/responses/NotAcceptable" "500": $ref: "../../../beacon-node-oapi.yaml#/components/responses/InternalError" diff --git a/apis/beacon/light_client/updates.yaml b/apis/beacon/light_client/updates.yaml index 4823d071..ec40d0d7 100644 --- a/apis/beacon/light_client/updates.yaml +++ b/apis/beacon/light_client/updates.yaml @@ -85,13 +85,6 @@ get: code: 400 message: "Missing `count` value" "406": - description: Unacceptable media type - content: - application/json: - schema: - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage" - example: - code: 406 - message: "Accepted media type not supported" + $ref: "../../../beacon-node-oapi.yaml#/components/responses/NotAcceptable" "500": $ref: "../../../beacon-node-oapi.yaml#/components/responses/InternalError" diff --git a/apis/builder/states/expected_withdrawals.yaml b/apis/builder/states/expected_withdrawals.yaml index a89475c0..1c11b367 100644 --- a/apis/builder/states/expected_withdrawals.yaml +++ b/apis/builder/states/expected_withdrawals.yaml @@ -56,5 +56,7 @@ get: example: code: 404 message: "State not found" + "406": + $ref: "../../../beacon-node-oapi.yaml#/components/responses/NotAcceptable" "500": $ref: '../../../beacon-node-oapi.yaml#/components/responses/InternalError' \ No newline at end of file diff --git a/apis/debug/state.v2.yaml b/apis/debug/state.v2.yaml index d58ed771..d413af1c 100644 --- a/apis/debug/state.v2.yaml +++ b/apis/debug/state.v2.yaml @@ -60,6 +60,8 @@ get: example: code: 404 message: "State not found" + "406": + $ref: "../../beacon-node-oapi.yaml#/components/responses/NotAcceptable" "500": $ref: '../../beacon-node-oapi.yaml#/components/responses/InternalError' diff --git a/apis/validator/blinded_block.yaml b/apis/validator/blinded_block.yaml index d8a6e6a8..90ca5659 100644 --- a/apis/validator/blinded_block.yaml +++ b/apis/validator/blinded_block.yaml @@ -72,6 +72,8 @@ get: value: code: 400 message: "Invalid request to produce a block" + "406": + $ref: "../../beacon-node-oapi.yaml#/components/responses/NotAcceptable" "500": $ref: '../../beacon-node-oapi.yaml#/components/responses/InternalError' "503": diff --git a/apis/validator/block.v2.yaml b/apis/validator/block.v2.yaml index ff3fc8cb..00ad2fc8 100644 --- a/apis/validator/block.v2.yaml +++ b/apis/validator/block.v2.yaml @@ -69,6 +69,8 @@ get: value: code: 400 message: "Invalid request to produce a block" + "406": + $ref: "../../beacon-node-oapi.yaml#/components/responses/NotAcceptable" "500": $ref: '../../beacon-node-oapi.yaml#/components/responses/InternalError' "503": diff --git a/apis/validator/block.v3.yaml b/apis/validator/block.v3.yaml index b5f4d858..f2adf9fe 100644 --- a/apis/validator/block.v3.yaml +++ b/apis/validator/block.v3.yaml @@ -125,6 +125,8 @@ get: value: code: 400 message: "Invalid request to produce a block" + "406": + $ref: "../../beacon-node-oapi.yaml#/components/responses/NotAcceptable" "500": $ref: '../../beacon-node-oapi.yaml#/components/responses/InternalError' "503": diff --git a/beacon-node-oapi.yaml b/beacon-node-oapi.yaml index c3608a84..3068d98d 100644 --- a/beacon-node-oapi.yaml +++ b/beacon-node-oapi.yaml @@ -6,9 +6,15 @@ info: API specification for the beacon node, which enables users to query and participate in Ethereum 2.0 phase 0 beacon chain. All requests by default send and receive JSON, and as such should have either or both of the "Content-Type: application/json" - and "Accept: application/json" headers. In addition, some requests can return data in the SSZ format. To indicate that SSZ - data is required in response to a request the header "Accept: application/octet-stream" should be sent. Note that only a subset - of requests can respond with data in SSZ format; these are noted in each individual request. + and "Accept: application/json" headers. In addition, some requests can send and receive data in the SSZ format. The header + "Content-Type: application/octet-stream" should be set in requests that contain SSZ data; a preference to receive SSZ data in + response can be indicated by setting the "Accept: application/octet-stream;q=1.0,application/json;q=0.9" header. Note that + only a subset of requests can respond with data in SSZ format; these are noted in each individual request. + + When handling requests, the server should return a 415 status code if the "Content-Type" header in the request specifies a format + that is not supported. Similarly, it should return a 406 status code if it cannot produce a response in the format accepted by + the client as specified in the "Accept" header; if no "Accept" header is provided then it is assumed to be "application/json". + In any case, the server should indicate the format of the response by setting the corresponding "Content-Type" header. API endpoints are individually versioned. As such, there is no direct relationship between all v1 endpoints, all v2 endpoints, _etc._ and no such relationship should be inferred. All JSON responses return the requested data under a `data` key in the top @@ -413,6 +419,8 @@ components: $ref: './types/http.yaml#/InvalidRequest' NotFound: $ref: './types/http.yaml#/NotFound' + NotAcceptable: + $ref: './types/http.yaml#/NotAcceptable' UnsupportedMediaType: $ref: './types/http.yaml#/UnsupportedMediaType' InternalError: diff --git a/types/http.yaml b/types/http.yaml index 60ec9a33..a0bee7aa 100644 --- a/types/http.yaml +++ b/types/http.yaml @@ -110,8 +110,31 @@ NotFound: example: code: 404 message: "Requested item not found" +NotAcceptable: + description: "Accepted media type is not supported." + content: + application/json: + schema: + type: object + required: [code, message] + properties: + code: + description: "The media type in \"Accept\" header is unsupported, and the request has been rejected. This occurs when the server cannot produce a response in the format accepted by the client." + type: number + example: 406 + message: + description: "Message describing error" + type: string + stacktraces: + description: "Optional stacktraces, sent when node is in debug mode" + type: array + items: + type: string + example: + code: 406 + message: "Accepted media type not supported" UnsupportedMediaType: - description: "The supplied content-type is not supported." + description: "Supplied content-type is not supported." content: application/json: schema: @@ -119,7 +142,7 @@ UnsupportedMediaType: required: [code, message] properties: code: - description: "The media type supplied is unsupported, and the request has been rejected. This occurs when a HTTP request supplies a payload in a content-type that the service is not able to accept." + description: "The media type in \"Content-Type\" header is unsupported, and the request has been rejected. This occurs when a HTTP request supplies a payload in a content-type that the server is not able to handle." type: number example: 415 message: From 78380ff8a3c3106a0c0b34550f1ba0a7649c6648 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rados=C5=82aw=20Kapka?= Date: Tue, 10 Sep 2024 20:56:46 -0400 Subject: [PATCH 2/7] Deprecate v1 block publishing (#467) Co-authored-by: Paul Harris --- apis/beacon/blocks/blinded_blocks.yaml | 1 + apis/beacon/blocks/blocks.yaml | 1 + 2 files changed, 2 insertions(+) diff --git a/apis/beacon/blocks/blinded_blocks.yaml b/apis/beacon/blocks/blinded_blocks.yaml index 1f545e57..f7da86ba 100644 --- a/apis/beacon/blocks/blinded_blocks.yaml +++ b/apis/beacon/blocks/blinded_blocks.yaml @@ -3,6 +3,7 @@ post: - Beacon - ValidatorRequiredApi summary: "Publish a signed block." + deprecated: true operationId: "publishBlindedBlock" description: | Instructs the beacon node to use the components of the `SignedBlindedBeaconBlock` to construct and publish a diff --git a/apis/beacon/blocks/blocks.yaml b/apis/beacon/blocks/blocks.yaml index 68be1b69..4c0a8517 100644 --- a/apis/beacon/blocks/blocks.yaml +++ b/apis/beacon/blocks/blocks.yaml @@ -3,6 +3,7 @@ post: - Beacon - ValidatorRequiredApi summary: "Publish a signed block." + deprecated: true operationId: "publishBlock" description: | Instructs the beacon node to broadcast a newly signed beacon block to the beacon network, From 6f55437b6cf4afdc2041b88b14f85f4f94023dff Mon Sep 17 00:00:00 2001 From: NC <17676176+ensi321@users.noreply.github.com> Date: Wed, 11 Sep 2024 20:10:21 -0700 Subject: [PATCH 3/7] Add Deneb and Electra light client spec (#468) Co-authored-by: Nico Flaig Co-authored-by: Paul Harris --- apis/beacon/light_client/bootstrap.yaml | 2 + apis/beacon/light_client/finality_update.yaml | 2 + .../light_client/optimistic_update.yaml | 2 + apis/beacon/light_client/updates.yaml | 6 +- beacon-node-oapi.yaml | 16 ++++ types/deneb/light_client.yaml | 64 ++++++++++++++++ types/electra/light_client.yaml | 75 +++++++++++++++++++ 7 files changed, 166 insertions(+), 1 deletion(-) create mode 100644 types/deneb/light_client.yaml create mode 100644 types/electra/light_client.yaml diff --git a/apis/beacon/light_client/bootstrap.yaml b/apis/beacon/light_client/bootstrap.yaml index b535f088..6e3c9544 100644 --- a/apis/beacon/light_client/bootstrap.yaml +++ b/apis/beacon/light_client/bootstrap.yaml @@ -32,6 +32,8 @@ get: anyOf: - $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Altair.LightClientBootstrap' - $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Capella.LightClientBootstrap' + - $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Deneb.LightClientBootstrap' + - $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Electra.LightClientBootstrap' application/octet-stream: schema: description: "SSZ serialized `LightClientBootstrap` bytes. Use Accept header to choose this response type" diff --git a/apis/beacon/light_client/finality_update.yaml b/apis/beacon/light_client/finality_update.yaml index 298480d7..3b2015ca 100644 --- a/apis/beacon/light_client/finality_update.yaml +++ b/apis/beacon/light_client/finality_update.yaml @@ -27,6 +27,8 @@ get: anyOf: - $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Altair.LightClientFinalityUpdate' - $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Capella.LightClientFinalityUpdate' + - $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Deneb.LightClientFinalityUpdate' + - $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Electra.LightClientFinalityUpdate' application/octet-stream: schema: description: "SSZ serialized `LightClientFinalityUpdate` bytes. Use Accept header to choose this response type" diff --git a/apis/beacon/light_client/optimistic_update.yaml b/apis/beacon/light_client/optimistic_update.yaml index 16cb2208..599b104b 100644 --- a/apis/beacon/light_client/optimistic_update.yaml +++ b/apis/beacon/light_client/optimistic_update.yaml @@ -27,6 +27,8 @@ get: anyOf: - $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Altair.LightClientOptimisticUpdate' - $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Capella.LightClientOptimisticUpdate' + - $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Deneb.LightClientOptimisticUpdate' + - $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Electra.LightClientOptimisticUpdate' application/octet-stream: schema: description: "SSZ serialized `LightClientOptimisticUpdate` bytes. Use Accept header to choose this response type" diff --git a/apis/beacon/light_client/updates.yaml b/apis/beacon/light_client/updates.yaml index ec40d0d7..d00b667c 100644 --- a/apis/beacon/light_client/updates.yaml +++ b/apis/beacon/light_client/updates.yaml @@ -37,6 +37,8 @@ get: anyOf: - $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Altair.LightClientUpdate' - $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Capella.LightClientUpdate' + - $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Deneb.LightClientUpdate' + - $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Electra.LightClientUpdate' application/octet-stream: schema: description: | @@ -60,7 +62,9 @@ get: | ------------------------------------------------------------------- | ------------------------------------- | | `GENESIS_FORK_VERSION` | n/a | | `ALTAIR_FORK_VERSION` through `BELLATRIX_FORK_VERSION` | `altair.LightClientUpdate` | - | `CAPELLA_FORK_VERSION` and later | `capella.LightClientUpdate` | + | `CAPELLA_FORK_VERSION` | `capella.LightClientUpdate` | + | `DENEB_FORK_VERSION` | `deneb.LightClientUpdate` | + | `ELECTRA_FORK_VERSION` and later | `electra.LightClientUpdate` | "400": description: Malformed or missing request parameter content: diff --git a/beacon-node-oapi.yaml b/beacon-node-oapi.yaml index 3068d98d..cc82777f 100644 --- a/beacon-node-oapi.yaml +++ b/beacon-node-oapi.yaml @@ -383,6 +383,14 @@ components: $ref: './types/deneb/block.yaml#/Deneb/BlindedBeaconBlock' Deneb.SignedBlindedBeaconBlock: $ref: './types/deneb/block.yaml#/Deneb/SignedBlindedBeaconBlock' + Deneb.LightClientBootstrap: + $ref: './types/deneb/light_client.yaml#/Deneb/LightClientBootstrap' + Deneb.LightClientUpdate: + $ref: './types/deneb/light_client.yaml#/Deneb/LightClientUpdate' + Deneb.LightClientFinalityUpdate: + $ref: './types/deneb/light_client.yaml#/Deneb/LightClientFinalityUpdate' + Deneb.LightClientOptimisticUpdate: + $ref: './types/deneb/light_client.yaml#/Deneb/LightClientOptimisticUpdate' Blob: $ref: './types/primitive.yaml#/Blob' Deneb.BlobSidecars: @@ -393,6 +401,14 @@ components: $ref: './types/electra/attester_slashing.yaml#/Electra/AttesterSlashing' Electra.SignedAggregateAndProof: $ref: './types/electra/validator.yaml#/Electra/SignedAggregateAndProof' + Electra.LightClientBootstrap: + $ref: './types/electra/light_client.yaml#/Electra/LightClientBootstrap' + Electra.LightClientUpdate: + $ref: './types/electra/light_client.yaml#/Electra/LightClientUpdate' + Electra.LightClientFinalityUpdate: + $ref: './types/electra/light_client.yaml#/Electra/LightClientFinalityUpdate' + Electra.LightClientOptimisticUpdate: + $ref: './types/electra/light_client.yaml#/Electra/LightClientOptimisticUpdate' Node: $ref: './types/fork_choice.yaml#/Node' ExtraData: diff --git a/types/deneb/light_client.yaml b/types/deneb/light_client.yaml new file mode 100644 index 00000000..64e01d1b --- /dev/null +++ b/types/deneb/light_client.yaml @@ -0,0 +1,64 @@ +Deneb: + LightClientHeader: + type: object + required: [beacon, execution, execution_branch] + properties: + beacon: + $ref: '../block.yaml#/BeaconBlockHeader' + execution: + $ref: './execution_payload.yaml#/Deneb/ExecutionPayloadHeader' + execution_branch: + $ref: '../capella/light_client.yaml#/Capella/ExecutionBranch' + + LightClientBootstrap: + type: object + required: [header, current_sync_committee, current_sync_committee_branch] + properties: + header: + $ref: '#/Deneb/LightClientHeader' + current_sync_committee: + $ref: '../altair/sync_committee.yaml#/Altair/SyncCommittee' + current_sync_committee_branch: + $ref: '../altair/light_client.yaml#/Altair/CurrentSyncCommitteeBranch' + LightClientUpdate: + type: object + required: [attested_header, next_sync_committee, next_sync_committee_branch, finalized_header, finality_branch, sync_aggregate, signature_slot] + properties: + attested_header: + $ref: '#/Deneb/LightClientHeader' + next_sync_committee: + $ref: '../altair/sync_committee.yaml#/Altair/SyncCommittee' + next_sync_committee_branch: + $ref: '../altair/light_client.yaml#/Altair/NextSyncCommitteeBranch' + finalized_header: + $ref: '#/Deneb/LightClientHeader' + finality_branch: + $ref: '../altair/light_client.yaml#/Altair/FinalityBranch' + sync_aggregate: + $ref: '../altair/sync_aggregate.yaml#/Altair/SyncAggregate' + signature_slot: + $ref: '../primitive.yaml#/Uint64' + LightClientFinalityUpdate: + type: object + required: [attested_header, finalized_header, finality_branch, sync_aggregate, signature_slot] + properties: + attested_header: + $ref: '#/Deneb/LightClientHeader' + finalized_header: + $ref: '#/Deneb/LightClientHeader' + finality_branch: + $ref: '../altair/light_client.yaml#/Altair/FinalityBranch' + sync_aggregate: + $ref: '../altair/sync_aggregate.yaml#/Altair/SyncAggregate' + signature_slot: + $ref: '../primitive.yaml#/Uint64' + LightClientOptimisticUpdate: + type: object + required: [attested_header, sync_aggregate, signature_slot] + properties: + attested_header: + $ref: '#/Deneb/LightClientHeader' + sync_aggregate: + $ref: '../altair/sync_aggregate.yaml#/Altair/SyncAggregate' + signature_slot: + $ref: '../primitive.yaml#/Uint64' diff --git a/types/electra/light_client.yaml b/types/electra/light_client.yaml new file mode 100644 index 00000000..01187cc9 --- /dev/null +++ b/types/electra/light_client.yaml @@ -0,0 +1,75 @@ +Electra: + FinalityBranch: + type: array + items: + $ref: '../primitive.yaml#/Root' + description: "Merkle proof consisting of [`log2trunc(FINALIZED_ROOT_GINDEX_ELECTRA])`](https://github.com/ethereum/consensus-specs/blob/v1.5.0-alpha.4/specs/electra/light-client/sync-protocol.md#constants) roots" + minItems: 7 + maxItems: 7 + CurrentSyncCommitteeBranch: + type: array + items: + $ref: '../primitive.yaml#/Root' + description: "Merkle proof consisting of [`log2trunc(CURRENT_SYNC_COMMITTEE_GINDEX_ELECTRA])`](https://github.com/ethereum/consensus-specs/blob/v1.5.0-alpha.4/specs/electra/light-client/sync-protocol.md#constants) roots" + minItems: 6 + maxItems: 6 + NextSyncCommitteeBranch: + type: array + items: + $ref: '../primitive.yaml#/Root' + description: "Merkle proof consisting of [`log2trunc(NEXT_SYNC_COMMITTEE_GINDEX_ELECTRA])`](https://github.com/ethereum/consensus-specs/blob/v1.5.0-alpha.4/specs/electra/light-client/sync-protocol.md#constants) roots" + minItems: 6 + maxItems: 6 + + LightClientBootstrap: + type: object + required: [header, current_sync_committee, current_sync_committee_branch] + properties: + header: + $ref: '../deneb/light_client.yaml#/Deneb/LightClientHeader' + current_sync_committee: + $ref: '../altair/sync_committee.yaml#/Altair/SyncCommittee' + current_sync_committee_branch: + $ref: '#/Electra/CurrentSyncCommitteeBranch' + LightClientUpdate: + type: object + required: [attested_header, next_sync_committee, next_sync_committee_branch, finalized_header, finality_branch, sync_aggregate, signature_slot] + properties: + attested_header: + $ref: '../deneb/light_client.yaml#/Deneb/LightClientHeader' + next_sync_committee: + $ref: '../altair/sync_committee.yaml#/Altair/SyncCommittee' + next_sync_committee_branch: + $ref: '#/Electra/NextSyncCommitteeBranch' + finalized_header: + $ref: '../deneb/light_client.yaml#/Deneb/LightClientHeader' + finality_branch: + $ref: '#/Electra/FinalityBranch' + sync_aggregate: + $ref: '../altair/sync_aggregate.yaml#/Altair/SyncAggregate' + signature_slot: + $ref: '../primitive.yaml#/Uint64' + LightClientFinalityUpdate: + type: object + required: [attested_header, finalized_header, finality_branch, sync_aggregate, signature_slot] + properties: + attested_header: + $ref: '../deneb/light_client.yaml#/Deneb/LightClientHeader' + finalized_header: + $ref: '../deneb/light_client.yaml#/Deneb/LightClientHeader' + finality_branch: + $ref: '#/Electra/FinalityBranch' + sync_aggregate: + $ref: '../altair/sync_aggregate.yaml#/Altair/SyncAggregate' + signature_slot: + $ref: '../primitive.yaml#/Uint64' + LightClientOptimisticUpdate: + type: object + required: [attested_header, sync_aggregate, signature_slot] + properties: + attested_header: + $ref: '../deneb/light_client.yaml#/Deneb/LightClientHeader' + sync_aggregate: + $ref: '../altair/sync_aggregate.yaml#/Altair/SyncAggregate' + signature_slot: + $ref: '../primitive.yaml#/Uint64' From ca2f9a8cbff300f458bc27d72bb0e4152936b318 Mon Sep 17 00:00:00 2001 From: Mehdi AOUADI Date: Thu, 12 Sep 2024 09:33:04 +0200 Subject: [PATCH 4/7] clarify the consensus version headers (#470) --- apis/beacon/blocks/attestations.v2.yaml | 1 + apis/beacon/blocks/blinded_blocks.v2.yaml | 2 +- apis/beacon/blocks/blinded_blocks.yaml | 2 +- apis/beacon/blocks/blocks.v2.yaml | 2 +- apis/beacon/blocks/blocks.yaml | 2 +- apis/beacon/pool/attestations.v2.yaml | 2 +- apis/beacon/pool/attester_slashings.v2.yaml | 2 +- apis/validator/aggregate_and_proofs.v2.yaml | 2 +- beacon-node-oapi.yaml | 4 +++- 9 files changed, 11 insertions(+), 8 deletions(-) diff --git a/apis/beacon/blocks/attestations.v2.yaml b/apis/beacon/blocks/attestations.v2.yaml index 785ed096..dbc6383b 100644 --- a/apis/beacon/blocks/attestations.v2.yaml +++ b/apis/beacon/blocks/attestations.v2.yaml @@ -15,6 +15,7 @@ get: headers: Eth-Consensus-Version: $ref: '../../../beacon-node-oapi.yaml#/components/headers/Eth-Consensus-Version' + description: "The active consensus version to which the attestations belong." content: application/json: schema: diff --git a/apis/beacon/blocks/blinded_blocks.v2.yaml b/apis/beacon/blocks/blinded_blocks.v2.yaml index 9d48718d..93e3b568 100644 --- a/apis/beacon/blocks/blinded_blocks.v2.yaml +++ b/apis/beacon/blocks/blinded_blocks.v2.yaml @@ -42,7 +42,7 @@ post: $ref: '../../../beacon-node-oapi.yaml#/components/schemas/ConsensusVersion' required: true name: Eth-Consensus-Version - description: "Version of the block being submitted." + description: "The active consensus version to which the block being submitted belongs." requestBody: description: "The `SignedBlindedBeaconBlock` object composed of `BlindedBeaconBlock` object (produced by beacon node) and validator signature." required: true diff --git a/apis/beacon/blocks/blinded_blocks.yaml b/apis/beacon/blocks/blinded_blocks.yaml index f7da86ba..73704485 100644 --- a/apis/beacon/blocks/blinded_blocks.yaml +++ b/apis/beacon/blocks/blinded_blocks.yaml @@ -21,7 +21,7 @@ post: $ref: '../../../beacon-node-oapi.yaml#/components/schemas/ConsensusVersion' required: false name: Eth-Consensus-Version - description: "Version of the block being submitted, if using SSZ encoding." + description: "The active consensus version to which the block being submitted belongs." requestBody: description: "The `SignedBlindedBeaconBlock` object composed of `BlindedBeaconBlock` object (produced by beacon node) and validator signature." required: true diff --git a/apis/beacon/blocks/blocks.v2.yaml b/apis/beacon/blocks/blocks.v2.yaml index 45959301..97e83766 100644 --- a/apis/beacon/blocks/blocks.v2.yaml +++ b/apis/beacon/blocks/blocks.v2.yaml @@ -41,7 +41,7 @@ post: $ref: '../../../beacon-node-oapi.yaml#/components/schemas/ConsensusVersion' required: true name: Eth-Consensus-Version - description: "Version of the block being submitted." + description: "The active consensus version to which the block being submitted belongs." requestBody: description: "The `SignedBeaconBlock` object composed of `BeaconBlock` object (produced by beacon node) and validator signature." required: true diff --git a/apis/beacon/blocks/blocks.yaml b/apis/beacon/blocks/blocks.yaml index 4c0a8517..e5813c29 100644 --- a/apis/beacon/blocks/blocks.yaml +++ b/apis/beacon/blocks/blocks.yaml @@ -20,7 +20,7 @@ post: $ref: '../../../beacon-node-oapi.yaml#/components/schemas/ConsensusVersion' required: false name: Eth-Consensus-Version - description: "Version of the block being submitted, if using SSZ encoding." + description: "The active consensus version to which the block being submitted belongs." requestBody: description: "The `SignedBeaconBlock` object composed of `BeaconBlock` object (produced by beacon node) and validator signature." required: true diff --git a/apis/beacon/pool/attestations.v2.yaml b/apis/beacon/pool/attestations.v2.yaml index 7a8be747..4e6f48f3 100644 --- a/apis/beacon/pool/attestations.v2.yaml +++ b/apis/beacon/pool/attestations.v2.yaml @@ -67,7 +67,7 @@ post: $ref: '../../../beacon-node-oapi.yaml#/components/schemas/ConsensusVersion' required: true name: Eth-Consensus-Version - description: "Version of the attestations being submitted." + description: "The consensus version to which the attestations being submitted belong." tags: - Beacon - ValidatorRequiredApi diff --git a/apis/beacon/pool/attester_slashings.v2.yaml b/apis/beacon/pool/attester_slashings.v2.yaml index 03b44d56..28bec5a6 100644 --- a/apis/beacon/pool/attester_slashings.v2.yaml +++ b/apis/beacon/pool/attester_slashings.v2.yaml @@ -42,7 +42,7 @@ post: $ref: '../../../beacon-node-oapi.yaml#/components/schemas/ConsensusVersion' required: true name: Eth-Consensus-Version - description: "Version of the attester slashing being submitted." + description: "The active consensus version to which the attester slashing being submitted belongs." tags: - Beacon requestBody: diff --git a/apis/validator/aggregate_and_proofs.v2.yaml b/apis/validator/aggregate_and_proofs.v2.yaml index 9d46f7e5..7f024972 100644 --- a/apis/validator/aggregate_and_proofs.v2.yaml +++ b/apis/validator/aggregate_and_proofs.v2.yaml @@ -11,7 +11,7 @@ post: $ref: '../../beacon-node-oapi.yaml#/components/schemas/ConsensusVersion' required: true name: Eth-Consensus-Version - description: "Version of the aggregate and proofs being submitted." + description: "The active consensus version to which the aggregate and proofs being submitted belong." requestBody: required: true content: diff --git a/beacon-node-oapi.yaml b/beacon-node-oapi.yaml index cc82777f..33ebff47 100644 --- a/beacon-node-oapi.yaml +++ b/beacon-node-oapi.yaml @@ -448,7 +448,9 @@ components: headers: Eth-Consensus-Version: - description: Required in response so client can deserialize returned json or ssz data more effectively. + description: | + The active consensus version to which the data belongs. Required in response so client can deserialize returned json or ssz data + more effectively. required: true schema: $ref: '#/components/schemas/ConsensusVersion' From 203410d04697520abb83b1c7e8a396e1b7878b1c Mon Sep 17 00:00:00 2001 From: Nico Flaig Date: Mon, 23 Sep 2024 03:38:41 +0100 Subject: [PATCH 5/7] Add Electra block and state objects from CL spec (#469) --- apis/beacon/blob_sidecars/blob_sidecars.yaml | 2 +- apis/beacon/blocks/blinded_block.yaml | 3 +- apis/beacon/blocks/blinded_blocks.v2.yaml | 1 + apis/beacon/blocks/blinded_blocks.yaml | 1 + apis/beacon/blocks/block.v2.yaml | 3 +- apis/beacon/blocks/blocks.v2.yaml | 1 + apis/beacon/blocks/blocks.yaml | 1 + apis/debug/state.v2.yaml | 3 +- apis/validator/blinded_block.yaml | 3 +- apis/validator/block.v2.yaml | 3 +- apis/validator/block.v3.yaml | 4 +- beacon-node-oapi.yaml | 12 ++ types/deneb/block.yaml | 8 +- types/electra/block.yaml | 108 +++++++++++++++++ types/electra/block_contents.yaml | 24 ++++ types/electra/consolidation.yaml | 27 +++++ types/electra/deposit.yaml | 32 +++++ types/electra/execution_requests.yaml | 21 ++++ types/electra/state.yaml | 121 +++++++++++++++++++ types/electra/withdrawal.yaml | 30 +++++ 20 files changed, 397 insertions(+), 11 deletions(-) create mode 100644 types/electra/block.yaml create mode 100644 types/electra/block_contents.yaml create mode 100644 types/electra/consolidation.yaml create mode 100644 types/electra/deposit.yaml create mode 100644 types/electra/execution_requests.yaml create mode 100644 types/electra/state.yaml create mode 100644 types/electra/withdrawal.yaml diff --git a/apis/beacon/blob_sidecars/blob_sidecars.yaml b/apis/beacon/blob_sidecars/blob_sidecars.yaml index 92b4e853..e65b4810 100644 --- a/apis/beacon/blob_sidecars/blob_sidecars.yaml +++ b/apis/beacon/blob_sidecars/blob_sidecars.yaml @@ -39,7 +39,7 @@ get: properties: version: type: string - enum: [phase0, altair, bellatrix, capella, deneb] + enum: [phase0, altair, bellatrix, capella, deneb, electra] example: "deneb" execution_optimistic: $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ExecutionOptimistic" diff --git a/apis/beacon/blocks/blinded_block.yaml b/apis/beacon/blocks/blinded_block.yaml index d85bce32..8c5f25c7 100644 --- a/apis/beacon/blocks/blinded_block.yaml +++ b/apis/beacon/blocks/blinded_block.yaml @@ -26,7 +26,7 @@ get: properties: version: type: string - enum: [phase0, altair, bellatrix, capella, deneb] + enum: [phase0, altair, bellatrix, capella, deneb, electra] example: "phase0" execution_optimistic: $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ExecutionOptimistic" @@ -39,6 +39,7 @@ get: - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Bellatrix.SignedBlindedBeaconBlock" - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Capella.SignedBlindedBeaconBlock" - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Deneb.SignedBlindedBeaconBlock" + - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Electra.SignedBlindedBeaconBlock" application/octet-stream: schema: description: "SSZ serialized block bytes. Use Accept header to choose this response type" diff --git a/apis/beacon/blocks/blinded_blocks.v2.yaml b/apis/beacon/blocks/blinded_blocks.v2.yaml index 93e3b568..24f0d091 100644 --- a/apis/beacon/blocks/blinded_blocks.v2.yaml +++ b/apis/beacon/blocks/blinded_blocks.v2.yaml @@ -55,6 +55,7 @@ post: - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Bellatrix.SignedBlindedBeaconBlock" - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Capella.SignedBlindedBeaconBlock" - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Deneb.SignedBlindedBeaconBlock" + - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Electra.SignedBlindedBeaconBlock" application/octet-stream: schema: description: "SSZ serialized block bytes. Use content type header to indicate that SSZ data is contained in the request body." diff --git a/apis/beacon/blocks/blinded_blocks.yaml b/apis/beacon/blocks/blinded_blocks.yaml index 73704485..b5b70fe5 100644 --- a/apis/beacon/blocks/blinded_blocks.yaml +++ b/apis/beacon/blocks/blinded_blocks.yaml @@ -34,6 +34,7 @@ post: - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Bellatrix.SignedBlindedBeaconBlock" - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Capella.SignedBlindedBeaconBlock" - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Deneb.SignedBlindedBeaconBlock" + - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Electra.SignedBlindedBeaconBlock" application/octet-stream: schema: description: "SSZ serialized block bytes. Use content type header to indicate that SSZ data is contained in the request body." diff --git a/apis/beacon/blocks/block.v2.yaml b/apis/beacon/blocks/block.v2.yaml index 9f2322de..05a41595 100644 --- a/apis/beacon/blocks/block.v2.yaml +++ b/apis/beacon/blocks/block.v2.yaml @@ -26,7 +26,7 @@ get: properties: version: type: string - enum: [phase0, altair, bellatrix, capella, deneb] + enum: [phase0, altair, bellatrix, capella, deneb, electra] example: "phase0" execution_optimistic: $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ExecutionOptimistic" @@ -39,6 +39,7 @@ get: - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Bellatrix.SignedBeaconBlock" - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Capella.SignedBeaconBlock" - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Deneb.SignedBeaconBlock" + - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Electra.SignedBeaconBlock" application/octet-stream: schema: description: "SSZ serialized block bytes. Use Accept header to choose this response type" diff --git a/apis/beacon/blocks/blocks.v2.yaml b/apis/beacon/blocks/blocks.v2.yaml index 97e83766..ec5a19ee 100644 --- a/apis/beacon/blocks/blocks.v2.yaml +++ b/apis/beacon/blocks/blocks.v2.yaml @@ -54,6 +54,7 @@ post: - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Bellatrix.SignedBeaconBlock" - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Capella.SignedBeaconBlock" - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Deneb.SignedBlockContents" + - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Electra.SignedBlockContents" application/octet-stream: schema: description: "SSZ serialized block bytes. Use content type header to indicate that SSZ data is contained in the request body." diff --git a/apis/beacon/blocks/blocks.yaml b/apis/beacon/blocks/blocks.yaml index e5813c29..c28fc714 100644 --- a/apis/beacon/blocks/blocks.yaml +++ b/apis/beacon/blocks/blocks.yaml @@ -33,6 +33,7 @@ post: - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Bellatrix.SignedBeaconBlock" - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Capella.SignedBeaconBlock" - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Deneb.SignedBlockContents" + - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Electra.SignedBlockContents" application/octet-stream: schema: description: "SSZ serialized block bytes. Use content type header to indicate that SSZ data is contained in the request body." diff --git a/apis/debug/state.v2.yaml b/apis/debug/state.v2.yaml index d413af1c..cdfa17a7 100644 --- a/apis/debug/state.v2.yaml +++ b/apis/debug/state.v2.yaml @@ -26,7 +26,7 @@ get: properties: version: type: string - enum: [ phase0, altair, bellatrix, capella, deneb ] + enum: [phase0, altair, bellatrix, capella, deneb, electra] example: "phase0" execution_optimistic: $ref: "../../beacon-node-oapi.yaml#/components/schemas/ExecutionOptimistic" @@ -39,6 +39,7 @@ get: - $ref: "../../beacon-node-oapi.yaml#/components/schemas/Bellatrix.BeaconState" - $ref: "../../beacon-node-oapi.yaml#/components/schemas/Capella.BeaconState" - $ref: "../../beacon-node-oapi.yaml#/components/schemas/Deneb.BeaconState" + - $ref: "../../beacon-node-oapi.yaml#/components/schemas/Electra.BeaconState" application/octet-stream: schema: description: "SSZ serialized state bytes. Use Accept header to choose this response type" diff --git a/apis/validator/blinded_block.yaml b/apis/validator/blinded_block.yaml index 90ca5659..72c60519 100644 --- a/apis/validator/blinded_block.yaml +++ b/apis/validator/blinded_block.yaml @@ -49,7 +49,7 @@ get: properties: version: type: string - enum: [ phase0, altair, bellatrix, capella, deneb ] + enum: [phase0, altair, bellatrix, capella, deneb, electra] example: "bellatrix" data: anyOf: @@ -58,6 +58,7 @@ get: - $ref: "../../beacon-node-oapi.yaml#/components/schemas/Bellatrix.BlindedBeaconBlock" - $ref: "../../beacon-node-oapi.yaml#/components/schemas/Capella.BlindedBeaconBlock" - $ref: "../../beacon-node-oapi.yaml#/components/schemas/Deneb.BlindedBeaconBlock" + - $ref: "../../beacon-node-oapi.yaml#/components/schemas/Electra.BlindedBeaconBlock" application/octet-stream: schema: description: "SSZ serialized block bytes. Use Accept header to choose this response type, version string is sent in header `Eth-Consensus-Version`." diff --git a/apis/validator/block.v2.yaml b/apis/validator/block.v2.yaml index 00ad2fc8..4ee38d0f 100644 --- a/apis/validator/block.v2.yaml +++ b/apis/validator/block.v2.yaml @@ -46,7 +46,7 @@ get: properties: version: type: string - enum: [ phase0, altair, bellatrix, capella, deneb ] + enum: [phase0, altair, bellatrix, capella, deneb, electra] example: "phase0" data: anyOf: @@ -55,6 +55,7 @@ get: - $ref: "../../beacon-node-oapi.yaml#/components/schemas/Bellatrix.BeaconBlock" - $ref: "../../beacon-node-oapi.yaml#/components/schemas/Capella.BeaconBlock" - $ref: "../../beacon-node-oapi.yaml#/components/schemas/Deneb.BlockContents" + - $ref: "../../beacon-node-oapi.yaml#/components/schemas/Electra.BlockContents" application/octet-stream: schema: description: "SSZ serialized block bytes. Use Accept header to choose this response type, version string is sent in header `Eth-Consensus-Version`." diff --git a/apis/validator/block.v3.yaml b/apis/validator/block.v3.yaml index f2adf9fe..3788717d 100644 --- a/apis/validator/block.v3.yaml +++ b/apis/validator/block.v3.yaml @@ -90,7 +90,7 @@ get: properties: version: type: string - enum: [ phase0, altair, bellatrix, capella, deneb ] + enum: [phase0, altair, bellatrix, capella, deneb, electra] example: "phase0" execution_payload_blinded: type: boolean @@ -111,6 +111,8 @@ get: - $ref: "../../beacon-node-oapi.yaml#/components/schemas/Capella.BlindedBeaconBlock" - $ref: "../../beacon-node-oapi.yaml#/components/schemas/Deneb.BlockContents" - $ref: "../../beacon-node-oapi.yaml#/components/schemas/Deneb.BlindedBeaconBlock" + - $ref: "../../beacon-node-oapi.yaml#/components/schemas/Electra.BlockContents" + - $ref: "../../beacon-node-oapi.yaml#/components/schemas/Electra.BlindedBeaconBlock" application/octet-stream: schema: description: "SSZ serialized block or blinded block bytes. Use Accept header to choose this response type, version string is sent in header `Eth-Consensus-Version` and block type in `Eth-Blinded-Payload`." diff --git a/beacon-node-oapi.yaml b/beacon-node-oapi.yaml index 33ebff47..59d1aefd 100644 --- a/beacon-node-oapi.yaml +++ b/beacon-node-oapi.yaml @@ -395,6 +395,18 @@ components: $ref: './types/primitive.yaml#/Blob' Deneb.BlobSidecars: $ref: './types/deneb/blob_sidecar.yaml#/Deneb/BlobSidecars' + Electra.BeaconState: + $ref: './types/electra/state.yaml#/Electra/BeaconState' + Electra.BlockContents: + $ref: './types/electra/block_contents.yaml#/Electra/BlockContents' + Electra.SignedBeaconBlock: + $ref: './types/electra/block.yaml#/Electra/SignedBeaconBlock' + Electra.SignedBlockContents: + $ref: './types/electra/block_contents.yaml#/Electra/SignedBlockContents' + Electra.BlindedBeaconBlock: + $ref: './types/electra/block.yaml#/Electra/BlindedBeaconBlock' + Electra.SignedBlindedBeaconBlock: + $ref: './types/electra/block.yaml#/Electra/SignedBlindedBeaconBlock' Electra.Attestation: $ref: './types/electra/attestation.yaml#/Electra/Attestation' Electra.AttesterSlashing: diff --git a/types/deneb/block.yaml b/types/deneb/block.yaml index 4891c25f..d58607a5 100644 --- a/types/deneb/block.yaml +++ b/types/deneb/block.yaml @@ -54,7 +54,7 @@ Deneb: $ref: './execution_payload.yaml#/Deneb/ExecutionPayload' BeaconBlock: - description: "The [`BeaconBlock`](https://github.com/ethereum/consensus-specs/blob/master/specs/deneb/beacon-chain.md#beaconblock) object from the CL Deneb spec." + description: "The [`BeaconBlock`](https://github.com/ethereum/consensus-specs/blob/master/specs/phase0/beacon-chain.md#beaconblock) object from the CL Deneb spec." allOf: - $ref: '../altair/block.yaml#/Altair/BeaconBlockCommon' - type: object @@ -65,7 +65,7 @@ Deneb: SignedBeaconBlock: type: object - description: "The [`SignedBeaconBlock`](https://github.com/ethereum/consensus-specs/blob/master/specs/deneb/beacon-chain.md#signedbeaconblock) object envelope from the CL Deneb spec." + description: "The [`SignedBeaconBlock`](https://github.com/ethereum/consensus-specs/blob/master/specs/phase0/beacon-chain.md#signedbeaconblock) object envelope from the CL Deneb spec." required: [message, signature] properties: message: @@ -84,7 +84,7 @@ Deneb: $ref: './execution_payload.yaml#/Deneb/ExecutionPayloadHeader' BlindedBeaconBlock: - description: "A variant of the [`BeaconBlock`](https://github.com/ethereum/consensus-specs/blob/master/specs/deneb/beacon-chain.md#beaconblock) object from the CL Deneb spec, which contains a `BlindedBeaconBlockBody` rather than a `BeaconBlockBody`." + description: "A variant of the [`BeaconBlock`](https://github.com/ethereum/consensus-specs/blob/master/specs/phase0/beacon-chain.md#beaconblock) object from the CL Deneb spec, which contains a `BlindedBeaconBlockBody` rather than a `BeaconBlockBody`." allOf: - $ref: '../altair/block.yaml#/Altair/BeaconBlockCommon' - type: object @@ -95,7 +95,7 @@ Deneb: SignedBlindedBeaconBlock: type: object - description: "A variant of the [`SignedBeaconBlock`](https://github.com/ethereum/consensus-specs/blob/master/specs/deneb/beacon-chain.md#signedbeaconblock) object envelope from the CL Deneb spec, which contains a `BlindedBeaconBlock` rather than a `BeaconBlock`." + description: "A variant of the [`SignedBeaconBlock`](https://github.com/ethereum/consensus-specs/blob/master/specs/phase0/beacon-chain.md#signedbeaconblock) object envelope from the CL Deneb spec, which contains a `BlindedBeaconBlock` rather than a `BeaconBlock`." required: [message, signature] properties: message: diff --git a/types/electra/block.yaml b/types/electra/block.yaml new file mode 100644 index 00000000..db460fd3 --- /dev/null +++ b/types/electra/block.yaml @@ -0,0 +1,108 @@ +Electra: + BeaconBlockBodyCommon: + # An abstract object to collect the common fields between the BeaconBlockBody and the BlindedBeaconBlockBody objects + type: object + description: "The [`BeaconBlockBody`](https://github.com/ethereum/consensus-specs/blob/v1.5.0-alpha.5/specs/electra/beacon-chain.md#beaconblockbody) object from the CL Electra spec." + required: [randao_reveal, eth1_data, graffiti, proposer_slashings, attester_slashings, attestations, deposits, voluntary_exits, sync_aggregate, bls_to_execution_changes, blob_kzg_commitments] + properties: + randao_reveal: + allOf: + - $ref: "../primitive.yaml#/Signature" + - description: "The RANDAO reveal value provided by the validator." + eth1_data: + $ref: "../eth1.yaml#/Eth1Data" + graffiti: + $ref: "../primitive.yaml#/Graffiti" + proposer_slashings: + type: array + items: + $ref: "../proposer_slashing.yaml#/ProposerSlashing" + attester_slashings: + type: array + items: + $ref: "./attester_slashing.yaml#/Electra/AttesterSlashing" + attestations: + type: array + items: + $ref: "./attestation.yaml#/Electra/Attestation" + deposits: + type: array + items: + $ref: "../deposit.yaml#/Deposit" + voluntary_exits: + type: array + items: + $ref: "../voluntary_exit.yaml#/SignedVoluntaryExit" + sync_aggregate: + $ref: "../altair/sync_aggregate.yaml#/Altair/SyncAggregate" + bls_to_execution_changes: + type: array + items: + $ref: "../bls_to_execution_change.yaml#/SignedBLSToExecutionChange" + blob_kzg_commitments: + type: array + items: + $ref: "../primitive.yaml#/KZGCommitment" + + BeaconBlockBody: + allOf: + - $ref: "#/Electra/BeaconBlockBodyCommon" + - type: object + required: [execution_payload, execution_requests] + properties: + execution_payload: + $ref: "../deneb/execution_payload.yaml#/Deneb/ExecutionPayload" + execution_requests: + $ref: "./execution_requests.yaml#/Electra/ExecutionRequests" + + BeaconBlock: + description: "The [`BeaconBlock`](https://github.com/ethereum/consensus-specs/blob/v1.5.0-alpha.5/specs/phase0/beacon-chain.md#beaconblock) object from the CL Electra spec." + allOf: + - $ref: "../altair/block.yaml#/Altair/BeaconBlockCommon" + - type: object + required: [body] + properties: + body: + $ref: "#/Electra/BeaconBlockBody" + + SignedBeaconBlock: + type: object + description: "The [`SignedBeaconBlock`](https://github.com/ethereum/consensus-specs/blob/v1.5.0-alpha.5/specs/phase0/beacon-chain.md#signedbeaconblock) object envelope from the CL Electra spec." + required: [message, signature] + properties: + message: + $ref: "#/Electra/BeaconBlock" + signature: + $ref: "../primitive.yaml#/Signature" + + BlindedBeaconBlockBody: + description: "A variant of the [`BeaconBlockBody`](https://github.com/ethereum/consensus-specs/blob/v1.5.0-alpha.5/specs/electra/beacon-chain.md#beaconblockbody) object from the CL Electra spec, which contains a transactions root rather than a full transactions list." + allOf: + - $ref: "#/Electra/BeaconBlockBodyCommon" + - type: object + required: [execution_payload_header, execution_requests_root] + properties: + execution_payload_header: + $ref: "../deneb/execution_payload.yaml#/Deneb/ExecutionPayloadHeader" + execution_requests_root: + $ref: "../primitive.yaml#/Root" + + BlindedBeaconBlock: + description: "A variant of the [`BeaconBlock`](https://github.com/ethereum/consensus-specs/blob/v1.5.0-alpha.5/specs/phase0/beacon-chain.md#beaconblock) object from the CL Electra spec, which contains a `BlindedBeaconBlockBody` rather than a `BeaconBlockBody`." + allOf: + - $ref: "../altair/block.yaml#/Altair/BeaconBlockCommon" + - type: object + required: [body] + properties: + body: + $ref: "#/Electra/BlindedBeaconBlockBody" + + SignedBlindedBeaconBlock: + type: object + description: "A variant of the [`SignedBeaconBlock`](https://github.com/ethereum/consensus-specs/blob/v1.5.0-alpha.5/specs/phase0/beacon-chain.md#signedbeaconblock) object envelope from the CL Electra spec, which contains a `BlindedBeaconBlock` rather than a `BeaconBlock`." + required: [message, signature] + properties: + message: + $ref: "#/Electra/BlindedBeaconBlock" + signature: + $ref: "../primitive.yaml#/Signature" diff --git a/types/electra/block_contents.yaml b/types/electra/block_contents.yaml new file mode 100644 index 00000000..d4a38519 --- /dev/null +++ b/types/electra/block_contents.yaml @@ -0,0 +1,24 @@ +Electra: + BlockContents: + type: object + description: "The required object for block production according to the Electra CL spec." + required: [block, kzg_proofs, blobs] + properties: + block: + $ref: "./block.yaml#/Electra/BeaconBlock" + kzg_proofs: + $ref: "../deneb/block_contents.yaml#/Deneb/KZGProofs" + blobs: + $ref: "../deneb/block_contents.yaml#/Deneb/Blobs" + + SignedBlockContents: + type: object + description: "The required signed components of block production according to the Electra CL spec." + required: [signed_block, kzg_proofs, blobs] + properties: + signed_block: + $ref: "./block.yaml#/Electra/SignedBeaconBlock" + kzg_proofs: + $ref: "../deneb/block_contents.yaml#/Deneb/KZGProofs" + blobs: + $ref: "../deneb/block_contents.yaml#/Deneb/Blobs" diff --git a/types/electra/consolidation.yaml b/types/electra/consolidation.yaml new file mode 100644 index 00000000..94b9a75e --- /dev/null +++ b/types/electra/consolidation.yaml @@ -0,0 +1,27 @@ +Electra: + ConsolidationRequest: + type: object + description: "The [`ConsolidationRequest`](https://github.com/ethereum/consensus-specs/blob/v1.5.0-alpha.5/specs/electra/beacon-chain.md#consolidationrequest) object from the CL Electra spec." + required: [source_address, source_pubkey, target_pubkey] + properties: + source_address: + $ref: "../primitive.yaml#/ExecutionAddress" + description: "Execution address which sent the request." + source_pubkey: + $ref: "../primitive.yaml#/Pubkey" + description: "BLS public key of validator to consolidate from." + target_pubkey: + $ref: "../primitive.yaml#/Pubkey" + description: "BLS public key of validator to consolidate to." + + PendingConsolidation: + type: object + description: "The [`PendingConsolidation`](https://github.com/ethereum/consensus-specs/blob/v1.5.0-alpha.5/specs/electra/beacon-chain.md#pendingconsolidation) object from the CL Electra spec." + required: [source_index, target_index] + properties: + source_index: + $ref: "../primitive.yaml#/Uint64" + description: "Index of validator to consolidate from." + target_index: + $ref: "../primitive.yaml#/Uint64" + description: "Index of validator to consolidate to." diff --git a/types/electra/deposit.yaml b/types/electra/deposit.yaml new file mode 100644 index 00000000..e124df7c --- /dev/null +++ b/types/electra/deposit.yaml @@ -0,0 +1,32 @@ +Electra: + DepositRequest: + type: object + description: "The [`DepositRequest`](https://github.com/ethereum/consensus-specs/blob/v1.5.0-alpha.5/specs/electra/beacon-chain.md#depositrequest) object from the CL Electra spec." + required: [pubkey, withdrawal_credentials, amount, signature, index] + properties: + pubkey: + $ref: "../primitive.yaml#/Pubkey" + description: "BLS public key of validator." + withdrawal_credentials: + $ref: "../primitive.yaml#/Root" + description: "The withdrawal credentials." + amount: + $ref: "../primitive.yaml#/Gwei" + description: "The value to be deposited (gwei)." + signature: + $ref: "../primitive.yaml#/Signature" + index: + $ref: "../primitive.yaml#/Uint64" + description: "The index of the deposit request." + + PendingBalanceDeposit: + type: object + description: "The [`PendingBalanceDeposit`](https://github.com/ethereum/consensus-specs/blob/v1.5.0-alpha.5/specs/electra/beacon-chain.md#pendingbalancedeposit) object from the CL Electra spec." + required: [index, amount] + properties: + index: + $ref: "../primitive.yaml#/Uint64" + description: "Index of validator in validator registry." + amount: + $ref: "../primitive.yaml#/Gwei" + description: "The value to be deposited (gwei)." diff --git a/types/electra/execution_requests.yaml b/types/electra/execution_requests.yaml new file mode 100644 index 00000000..1851c89b --- /dev/null +++ b/types/electra/execution_requests.yaml @@ -0,0 +1,21 @@ +Electra: + ExecutionRequests: + type: object + description: "The [`ExecutionRequests`](https://github.com/ethereum/consensus-specs/blob/v1.5.0-alpha.6/specs/electra/beacon-chain.md#executionrequests) object from the CL Electra spec." + required: [deposits, withdrawals, consolidations] + properties: + deposits: + type: array + items: + $ref: "./deposit.yaml#/Electra/DepositRequest" + maxItems: 8192 + withdrawals: + type: array + items: + $ref: "./withdrawal.yaml#/Electra/WithdrawalRequest" + maxItems: 16 + consolidations: + type: array + items: + $ref: "./consolidation.yaml#/Electra/ConsolidationRequest" + maxItems: 1 diff --git a/types/electra/state.yaml b/types/electra/state.yaml new file mode 100644 index 00000000..7798a372 --- /dev/null +++ b/types/electra/state.yaml @@ -0,0 +1,121 @@ +Electra: + BeaconState: + type: object + description: "The [`BeaconState`](https://github.com/ethereum/consensus-specs/blob/v1.5.0-alpha.5/specs/electra/beacon-chain.md#beaconstate) object from the CL Electra spec." + required: [genesis_time, genesis_validators_root, slot, fork, latest_block_header, block_roots, state_roots, historical_roots, eth1_data, eth1_data_votes, eth1_deposit_index, validators, balances, randao_mixes, slashings, previous_epoch_participation, current_epoch_participation, justification_bits, previous_justified_checkpoint, current_justified_checkpoint, finalized_checkpoint, inactivity_scores, current_sync_committee, next_sync_committee, latest_execution_payload_header, next_withdrawal_index, next_withdrawal_validator_index, historical_summaries, deposit_requests_start_index, deposit_balance_to_consume, exit_balance_to_consume, earliest_exit_epoch, consolidation_balance_to_consume, earliest_consolidation_epoch, pending_balance_deposits, pending_partial_withdrawals, pending_consolidations] + properties: + genesis_time: + $ref: "../primitive.yaml#/Uint64" + genesis_validators_root: + $ref: "../primitive.yaml#/Root" + slot: + $ref: "../primitive.yaml#/Uint64" + fork: + $ref: "../misc.yaml#/Fork" + latest_block_header: + $ref: "../block.yaml#/BeaconBlockHeader" + block_roots: + type: array + description: "Fixed length of 8192 items" + items: + $ref: "../primitive.yaml#/Root" + state_roots: + type: array + description: "Fixed length of 8192 items" + items: + $ref: "../primitive.yaml#/Root" + historical_roots: + type: array + description: "Variable length list, maximum 16777216 items. Frozen in Capella, replaced by historical_summaries." + items: + $ref: "../primitive.yaml#/Root" + eth1_data: + $ref: "../eth1.yaml#/Eth1Data" + eth1_data_votes: + type: array + description: "Fixed length of 1024 items" + items: + $ref: "../eth1.yaml#/Eth1Data" + maxItems: 1024 + eth1_deposit_index: + $ref: "../primitive.yaml#/Uint64" + validators: + type: array + description: "Variable length list, maximum 1099511627776 items" + items: + $ref: "../validator.yaml#/Validator" + balances: + type: array + description: "Validator balances in gwei. Variable length list, maximum 1099511627776 items" + items: + $ref: '../primitive.yaml#/Uint64' + randao_mixes: + type: array + description: "Fixed length of 65536 items" + items: + $ref: "../primitive.yaml#/Bytes32" + slashings: + type: array + description: "Per-epoch sums of slashed effective balances. Fixed length of 8192 items" + items: + $ref: "../primitive.yaml#/Uint64" + previous_epoch_participation: + $ref: "../altair/epoch_participation.yaml#/Altair/EpochParticipation" + current_epoch_participation: + $ref: "../altair/epoch_participation.yaml#/Altair/EpochParticipation" + justification_bits: + $ref: "../primitive.yaml#/BitList" + description: "Bit set for every recent justified epoch" + previous_justified_checkpoint: + $ref: "../misc.yaml#/Checkpoint" + current_justified_checkpoint: + $ref: "../misc.yaml#/Checkpoint" + finalized_checkpoint: + $ref: "../misc.yaml#/Checkpoint" + inactivity_scores: + description: "Per-validator inactivity scores. Introduced in Altair. Variable length list, maximum 1099511627776 items" + type: array + items: + $ref: "../primitive.yaml#/Uint64" + current_sync_committee: + $ref: "../altair/sync_committee.yaml#/Altair/SyncCommittee" + next_sync_committee: + $ref: "../altair/sync_committee.yaml#/Altair/SyncCommittee" + latest_execution_payload_header: + $ref: "../deneb/execution_payload.yaml#/Deneb/ExecutionPayloadHeader" + next_withdrawal_index: + $ref: "../primitive.yaml#/Uint64" + next_withdrawal_validator_index: + $ref: "../primitive.yaml#/Uint64" + historical_summaries: + type: array + items: + $ref: "../capella/historical_summary.yaml#/Capella/HistoricalSummary" + description: "Variable length list, maximum 16777216 items" + deposit_requests_start_index: + $ref: "../primitive.yaml#/Uint64" + deposit_balance_to_consume: + $ref: "../primitive.yaml#/Gwei" + exit_balance_to_consume: + $ref: "../primitive.yaml#/Gwei" + earliest_exit_epoch: + $ref: "../primitive.yaml#/Uint64" + consolidation_balance_to_consume: + $ref: "../primitive.yaml#/Gwei" + earliest_consolidation_epoch: + $ref: "../primitive.yaml#/Uint64" + pending_balance_deposits: + type: array + items: + $ref: "./deposit.yaml#/Electra/PendingBalanceDeposit" + maxItems: 134217728 + pending_partial_withdrawals: + type: array + items: + $ref: "./withdrawal.yaml#/Electra/PendingPartialWithdrawal" + maxItems: 134217728 + pending_consolidations: + type: array + items: + $ref: "./consolidation.yaml#/Electra/PendingConsolidation" + maxItems: 262144 diff --git a/types/electra/withdrawal.yaml b/types/electra/withdrawal.yaml new file mode 100644 index 00000000..bca58715 --- /dev/null +++ b/types/electra/withdrawal.yaml @@ -0,0 +1,30 @@ +Electra: + WithdrawalRequest: + type: object + description: "The [`WithdrawalRequest`](https://github.com/ethereum/consensus-specs/blob/v1.5.0-alpha.5/specs/electra/beacon-chain.md#withdrawalrequest) object from the CL Electra spec." + required: [source_address, validator_pubkey, amount] + properties: + source_address: + $ref: "../primitive.yaml#/ExecutionAddress" + description: "Execution address which sent the request." + validator_pubkey: + $ref: "../primitive.yaml#/Pubkey" + description: "BLS public key of validator." + amount: + $ref: "../primitive.yaml#/Gwei" + description: "The value to be withdrawn (gwei)." + + PendingPartialWithdrawal: + type: object + description: "The [`PendingPartialWithdrawal`](https://github.com/ethereum/consensus-specs/blob/v1.5.0-alpha.5/specs/electra/beacon-chain.md#pendingpartialwithdrawal) object from the CL Electra spec." + required: [index, amount, withdrawable_epoch] + properties: + index: + $ref: "../primitive.yaml#/Uint64" + description: "Index of validator in validator registry." + amount: + $ref: "../primitive.yaml#/Uint64" + description: "The value to be withdrawn (gwei)." + withdrawable_epoch: + $ref: "../primitive.yaml#/Uint64" + description: "The epoch when the amount is withdrawable." From 30f056852c2a4ffdb97c4187112d7b307d08a3b9 Mon Sep 17 00:00:00 2001 From: Jim McDonald Date: Tue, 24 Sep 2024 22:52:29 +0100 Subject: [PATCH 6/7] Validator identities endpoint. (#452) In support of #449. Co-authored-by: Paul Harris Co-authored-by: Nico Flaig --- CHANGES.md | 1 + apis/beacon/states/validator_identities.yaml | 71 ++++++++++++++++++++ beacon-node-oapi.yaml | 4 ++ types/api.yaml | 14 ++++ 4 files changed, 90 insertions(+) create mode 100644 apis/beacon/states/validator_identities.yaml diff --git a/CHANGES.md b/CHANGES.md index 235c8c63..dda3467d 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -14,6 +14,7 @@ There are likely to be descriptions etc outside of the list below, but new query | [#448](https://github.com/ethereum/beacon-APIs/pull/448) `POST /eth/v2/beacon/pool/attestations` added | | | | | | | [#448](https://github.com/ethereum/beacon-APIs/pull/448) `GET /eth/v2/beacon/pool/attester_slashings` added | | | | | | | [#448](https://github.com/ethereum/beacon-APIs/pull/448) `POST /eth/v2/beacon/pool/attester_slashings` added | | | | | | +| [#452](https://github.com/ethereum/beacon-APIs/pull/452) `POST /eth/v1/beacon/states/{state_id}/validator_identities` added | | | | | | | [#456](https://github.com/ethereum/beacon-APIs/pull/456) `POST /eth/v2/validator/aggregate_and_proofs` added | | | | | | diff --git a/apis/beacon/states/validator_identities.yaml b/apis/beacon/states/validator_identities.yaml new file mode 100644 index 00000000..4963f5c3 --- /dev/null +++ b/apis/beacon/states/validator_identities.yaml @@ -0,0 +1,71 @@ +post: + operationId: "postStateValidatorIdentities" + summary: "Get validator identities from state" + description: | + Returns filterable list of validators identities. + + Identities will be returned for all indices or public keys that match known validators. If an index or public key does not + match any known validator, no identity will be returned but this will not cause an error. There are no guarantees for the + returned data in terms of ordering. + + Depending on `Accept` header data can be returned either as JSON or as bytes serialized by SSZ. + tags: + - Beacon + parameters: + - name: state_id + in: path + $ref: '../../../beacon-node-oapi.yaml#/components/parameters/StateId' + requestBody: + description: "An array of values, with each value either a hex encoded public key (any bytes48 with 0x prefix) or a validator index." + required: false + content: + application/json: + schema: + type: array + uniqueItems: true + items: + description: "Either hex encoded public key (any bytes48 with 0x prefix) or validator index" + type: string + responses: + "200": + description: Success + content: + application/json: + schema: + title: PostStateValidatorIdentitiesResponse + type: object + required: [execution_optimistic, finalized, data] + properties: + execution_optimistic: + $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ExecutionOptimistic" + finalized: + $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Finalized" + data: + type: array + items: + $ref: '../../../beacon-node-oapi.yaml#/components/schemas/ValidatorIdentityResponse' + application/octet-stream: + schema: + description: "SSZ serialized results. Use Accept header to choose this response type" + "400": + description: "Invalid state ID or malformed request" + content: + application/json: + schema: + $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage" + example: + code: 400 + message: "Invalid state ID: current" + "404": + description: "State not found" + content: + application/json: + schema: + $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage" + example: + code: 404 + message: "State not found" + "406": + $ref: "../../../beacon-node-oapi.yaml#/components/responses/NotAcceptable" + "500": + $ref: '../../../beacon-node-oapi.yaml#/components/responses/InternalError' diff --git a/beacon-node-oapi.yaml b/beacon-node-oapi.yaml index 59d1aefd..31a60561 100644 --- a/beacon-node-oapi.yaml +++ b/beacon-node-oapi.yaml @@ -81,6 +81,8 @@ paths: $ref: "./apis/beacon/states/validator.yaml" /eth/v1/beacon/states/{state_id}/validator_balances: $ref: "./apis/beacon/states/validator_balances.yaml" + /eth/v1/beacon/states/{state_id}/validator_identities: + $ref: "./apis/beacon/states/validator_identities.yaml" /eth/v1/beacon/states/{state_id}/committees: $ref: "./apis/beacon/states/committee.yaml" /eth/v1/beacon/states/{state_id}/sync_committees: @@ -239,6 +241,8 @@ components: $ref: './types/api.yaml#/ValidatorResponse' ValidatorBalanceResponse: $ref: './types/api.yaml#/ValidatorBalanceResponse' + ValidatorIdentityResponse: + $ref: './types/api.yaml#/ValidatorIdentityResponse' ValidatorStatus: $ref: './types/api.yaml#/ValidatorStatus' Committee: diff --git a/types/api.yaml b/types/api.yaml index 8d1dd9fc..8b577e16 100644 --- a/types/api.yaml +++ b/types/api.yaml @@ -45,6 +45,20 @@ ValidatorBalanceResponse: $ref: "./primitive.yaml#/Gwei" description: "Current validator balance in gwei." +ValidatorIdentityResponse: + type: object + required: [index, pubkey, activation_epoch] + properties: + index: + $ref: './primitive.yaml#/Uint64' + description: "Index of validator in validator registry." + pubkey: + $ref: './primitive.yaml#/Pubkey' + description: "Public key of validator." + activation_epoch: + $ref: "./primitive.yaml#/Uint64" + description: "Epoch when validator activated. 'FAR_FUTURE_EPOCH' if not activated" + ValidatorStatus: description: | Possible statuses: From e7f7d70423b0abfe9d9f33b701be2ec03e44eb02 Mon Sep 17 00:00:00 2001 From: Fredrik Svantes Date: Tue, 24 Sep 2024 23:56:36 +0200 Subject: [PATCH 7/7] Removed default builder boost (#438) Co-authored-by: Paul Harris --- apis/validator/block.v3.yaml | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/apis/validator/block.v3.yaml b/apis/validator/block.v3.yaml index 3788717d..b1eb5cc7 100644 --- a/apis/validator/block.v3.yaml +++ b/apis/validator/block.v3.yaml @@ -53,18 +53,17 @@ get: Servers must support the following values of the boost factor which encode common preferences: - * `builder_boost_factor=0`: prefer the execution node payload unless an error makes it + * `builder_boost_factor=0`: prefer the local execution node payload unless an error makes it unviable. - * `builder_boost_factor=100`: default profit maximization mode; choose whichever + * `builder_boost_factor=100`: profit maximization mode; choose whichever payload pays more. - * `builder_boost_factor=2**64 - 1`: prefer the builder payload unless an error or + * `builder_boost_factor=2**64 - 1`: prefer the external builder payload 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 this parameter is provided and the beacon node is not configured with a builder then the beacon node MUST - respond with a full block, which the caller can choose to reject if it wishes. If this - parameter is **not** provided then it should be treated as having the default value of 100. + respond with a full block, 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: