From 683a1e7144cd8db5c925e1aa6d36581b166fe00c Mon Sep 17 00:00:00 2001 From: shane-moore Date: Wed, 3 Sep 2025 14:38:48 -0700 Subject: [PATCH 01/42] modified block production end points --- apis/beacon/blocks/blocks.v2.yaml | 3 +- apis/validator/block.v3.yaml | 12 ++-- beacon-node-oapi.yaml | 21 ++++--- types/gloas/block.yaml | 77 ++++++++++++++++++++++++++ types/gloas/execution_payload_bid.yaml | 34 ++++++++++++ types/gloas/payload_attestations.yaml | 28 ++++++++++ 6 files changed, 160 insertions(+), 15 deletions(-) create mode 100644 types/gloas/block.yaml create mode 100644 types/gloas/execution_payload_bid.yaml create mode 100644 types/gloas/payload_attestations.yaml diff --git a/apis/beacon/blocks/blocks.v2.yaml b/apis/beacon/blocks/blocks.v2.yaml index 7019e0d5..ef4eb0a0 100644 --- a/apis/beacon/blocks/blocks.v2.yaml +++ b/apis/beacon/blocks/blocks.v2.yaml @@ -11,7 +11,7 @@ post: The beacon node is also expected to integrate the block into the state, but may broadcast it before doing so, so as to aid timely delivery of the block. Should the block fail full validation, a separate success response code (202) is used to indicate that the block was - successfully broadcast but failed integration. After Deneb, this additionally instructs + successfully broadcast but failed integration. After Deneb and before Gloas, this additionally instructs the beacon node to broadcast all given blobs. The broadcast behaviour may be adjusted via the `broadcast_validation` query parameter. parameters: @@ -49,6 +49,7 @@ post: application/json: schema: anyOf: + - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Gloas.SignedBeaconBlock" - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Fulu.SignedBlockContents" - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Electra.SignedBlockContents" - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Deneb.SignedBlockContents" diff --git a/apis/validator/block.v3.yaml b/apis/validator/block.v3.yaml index 18923ee9..67753872 100644 --- a/apis/validator/block.v3.yaml +++ b/apis/validator/block.v3.yaml @@ -5,13 +5,13 @@ get: operationId: "produceBlockV3" summary: "Produce a new block, without signature." description: | - Requests a beacon node to produce a valid block, which can then be signed by a validator. The - returned block may be blinded or unblinded, depending on the current state of the network as - decided by the execution and beacon nodes. + Requests a beacon node to produce a valid block, which can then be signed by a validator. - The beacon node must return an unblinded block if it obtains the execution payload from its - paired execution node. It must only return a blinded block if it obtains the execution payload - header from an MEV relay. + 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. For pre-Gloas forks, the returned block may be blinded or unblinded, depending on the current + state of the network as decided by the execution and beacon nodes. The beacon node returns an + unblinded block if it obtains the execution payload from its paired execution node, or a + blinded block if it obtains the execution payload header from an MEV relay. Metadata in the response indicates the type of block produced, and the supported types of block will be added to as forks progress. diff --git a/beacon-node-oapi.yaml b/beacon-node-oapi.yaml index dcae233d..e03840ba 100644 --- a/beacon-node-oapi.yaml +++ b/beacon-node-oapi.yaml @@ -333,8 +333,8 @@ components: $ref: './types/bellatrix/block.yaml#/Bellatrix/SignedBlindedBeaconBlock' ConsensusVersion: type: string - enum: [phase0, altair, bellatrix, capella, deneb, electra, fulu] - example: "fulu" + enum: [phase0, altair, bellatrix, capella, deneb, electra, fulu, gloas] + example: "gloas" SignedValidatorRegistration: $ref: './types/registration.yaml#/SignedValidatorRegistration' Capella.BeaconState: @@ -427,6 +427,10 @@ components: $ref: './types/electra/withdrawal.yaml#/Electra/PendingPartialWithdrawal' Fulu.BeaconState: $ref: './types/fulu/state.yaml#/Fulu/BeaconState' + Gloas.BeaconBlock: + $ref: "./types/gloas/block.yaml#/Gloas/BeaconBlock" + Gloas.SignedBeaconBlock: + $ref: "./types/gloas/block.yaml#/Gloas/SignedBeaconBlock" Fulu.BlockContents: $ref: "./types/fulu/block_contents.yaml#/Fulu/BlockContents" Fulu.SignedBlockContents: @@ -473,21 +477,22 @@ components: headers: Eth-Consensus-Version: description: | - The active consensus version to which the data belongs. Required in response so client can deserialize returned json or ssz data + 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' Eth-Execution-Payload-Blinded: - description: Required in response so client can deserialize returned json or ssz data to the correct object. - required: true + description: "DEPRECATED: Not applicable for gloas fork. For pre-gloas forks, this is required in response so client can deserialize returned json or ssz data to the correct object pre-gloas. Post-gloas, there is no concept of blinded blocks." + required: false schema: type: boolean Eth-Execution-Payload-Value: description: | - Execution payload value in Wei. Required in response so client can determine relative value - of execution payloads. - required: true + DEPRECATED: Not applicable for gloas fork. + For pre-gloas forks, this is the execution payload value in Wei. Required in response so client can determine relative value + of execution payloads pre-gloas. Post-gloas, the ExecutionPayloadBid defines the value of an execution payload. + required: false schema: $ref: './types/primitive.yaml#/Wei' Eth-Consensus-Block-Value: diff --git a/types/gloas/block.yaml b/types/gloas/block.yaml new file mode 100644 index 00000000..defc7bfd --- /dev/null +++ b/types/gloas/block.yaml @@ -0,0 +1,77 @@ +Gloas: + 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/master/specs/gloas/beacon-chain.md#beaconblockbody) object from the CL Gloas spec." + required: [randao_reveal, eth1_data, graffiti, proposer_slashings, attester_slashings, attestations, deposits, voluntary_exits, sync_aggregate, bls_to_execution_changes] + properties: + randao_reveal: + allOf: + - $ref: "../primitive.yaml#/Signature" + - description: "The RANDAO reveal value provided by the validator." + eth1_data: + $ref: "../phase0/eth1.yaml#/Phase0/Eth1Data" + graffiti: + $ref: "../primitive.yaml#/Graffiti" + proposer_slashings: + type: array + items: + $ref: "../phase0/proposer_slashing.yaml#/Phase0/ProposerSlashing" + attester_slashings: + type: array + items: + $ref: "../electra/attester_slashing.yaml#/Electra/AttesterSlashing" + attestations: + type: array + items: + $ref: "../electra/attestation.yaml#/Electra/Attestation" + deposits: + type: array + items: + $ref: "../phase0/deposit.yaml#/Phase0/Deposit" + voluntary_exits: + type: array + items: + $ref: "../phase0/voluntary_exit.yaml#/Phase0/SignedVoluntaryExit" + sync_aggregate: + $ref: "../altair/sync_aggregate.yaml#/Altair/SyncAggregate" + bls_to_execution_changes: + type: array + items: + $ref: "../capella/bls_to_execution_change.yaml#/Capella/SignedBLSToExecutionChange" + + BeaconBlockBody: + allOf: + - $ref: "#/Gloas/BeaconBlockBodyCommon" + - type: object + required: [signed_execution_payload_bid, payload_attestations] + properties: + signed_execution_payload_bid: + $ref: "./execution_payload_bid.yaml#/Gloas/SignedExecutionPayloadBid" + payload_attestations: + type: array + description: "Array of payload attestations from gloas." + items: + $ref: "./payload_attestations.yaml#/Gloas/PayloadAttestation" + minItems: 0 + maxItems: 4 + + BeaconBlock: + description: "The [`BeaconBlock`](https://github.com/ethereum/consensus-specs/blob/v1.5.0/specs/phase0/beacon-chain.md#beaconblock) object from the CL Gloas spec." + allOf: + - $ref: "../altair/block.yaml#/Altair/BeaconBlockCommon" + - type: object + required: [body] + properties: + body: + $ref: "#/Gloas/BeaconBlockBody" + + SignedBeaconBlock: + type: object + description: "The [`SignedBeaconBlock`](https://github.com/ethereum/consensus-specs/blob/v1.5.0/specs/phase0/beacon-chain.md#signedbeaconblock) object envelope from the CL Gloas spec." + required: [message, signature] + properties: + message: + $ref: "#/Gloas/BeaconBlock" + signature: + $ref: "../primitive.yaml#/Signature" diff --git a/types/gloas/execution_payload_bid.yaml b/types/gloas/execution_payload_bid.yaml new file mode 100644 index 00000000..771d2d77 --- /dev/null +++ b/types/gloas/execution_payload_bid.yaml @@ -0,0 +1,34 @@ +Gloas: + ExecutionPayloadBid: + type: object + description: "The [ExecutionPayloadBid](https://github.com/ethereum/consensus-specs/blob/master/specs/gloas/beacon-chain.md#executionpayloadbid) object from the CL gloas spec." + required: [parent_block_hash, parent_block_root, block_hash, fee_recipient, gas_limit, builder_index, slot, value, blob_kzg_commitments_root] + properties: + parent_block_hash: + $ref: "../primitive.yaml#/Root" + parent_block_root: + $ref: "../primitive.yaml#/Root" + block_hash: + $ref: "../primitive.yaml#/Root" + fee_recipient: + $ref: "../primitive.yaml#/ExecutionAddress" + gas_limit: + $ref: "../primitive.yaml#/Uint64" + builder_index: + $ref: "../primitive.yaml#/Uint64" + slot: + $ref: "../primitive.yaml#/Uint64" + value: + $ref: "../primitive.yaml#/Gwei" + blob_kzg_commitments_root: + $ref: "../primitive.yaml#/Root" + + SignedExecutionPayloadBid: + type: object + description: "The [SignedExecutionPayloadBid](https://github.com/ethereum/consensus-specs/blob/master/specs/gloas/beacon-chain.md#signedexecutionpayloadbid) object from the CL gloas spec." + required: [message, signature] + properties: + message: + $ref: "#/Gloas/ExecutionPayloadBid" + signature: + $ref: "../primitive.yaml#/Signature" diff --git a/types/gloas/payload_attestations.yaml b/types/gloas/payload_attestations.yaml new file mode 100644 index 00000000..80f654a0 --- /dev/null +++ b/types/gloas/payload_attestations.yaml @@ -0,0 +1,28 @@ +Gloas: + PayloadAttestation: + type: object + description: "The [PayloadAttestation](https://github.com/ethereum/consensus-specs/blob/master/specs/gloas/beacon-chain.md#payloadattestation) object from the CL gloas spec." + required: [aggregation_bits, data, signature] + properties: + aggregation_bits: + $ref: "../primitive.yaml#/BitList" + data: + $ref: "#/Gloas/PayloadAttestationData" + signature: + $ref: "../primitive.yaml#/Signature" + + PayloadAttestationData: + type: object + description: "The [PayloadAttestationData](https://github.com/ethereum/consensus-specs/blob/master/specs/gloas/beacon-chain.md#payloadattestationdata) object from the CL gloas spec." + required: [beacon_block_root, slot, payload_present, blob_data_available] + properties: + beacon_block_root: + $ref: "../primitive.yaml#/Root" + slot: + $ref: "../primitive.yaml#/Uint64" + payload_present: + type: boolean + description: "Whether the execution payload is present" + blob_data_available: + type: boolean + description: "Whether blob data is available" From 757f072bd53fc5eb34a55bc2d7d748563b598baf Mon Sep 17 00:00:00 2001 From: shane-moore Date: Thu, 4 Sep 2025 14:24:02 -0700 Subject: [PATCH 02/42] epbs execution_payload_bid get and post --- CHANGES.md | 9 +++ apis/beacon/execution_payload/bid.yaml | 41 ++++++++++++++ apis/validator/execution_payload_bid.yaml | 69 +++++++++++++++++++++++ beacon-node-oapi.yaml | 8 +++ wordlist.txt | 1 + 5 files changed, 128 insertions(+) create mode 100644 apis/beacon/execution_payload/bid.yaml create mode 100644 apis/validator/execution_payload_bid.yaml diff --git a/CHANGES.md b/CHANGES.md index 1d15402f..0f74dad5 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -8,6 +8,15 @@ 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) | |---------------------------------------------------------------------------------------------------------------------|--------------------------------------------------|---------------------------------------------------|----------------------------------------------------|-------------------------------------------------|-------------------------------------------| +| [#552](https://github.com/ethereum/beacon-APIs/pull/552) `GET /eth/v1/validator/execution_payload_bid/{slot}/{builder_index}` added | | | | | | +| [#552](https://github.com/ethereum/beacon-APIs/pull/552) `GET /eth/v1/validator/execution_payload_envelope/{slot}/{builder_index}` added | | | | | | +| [#552](https://github.com/ethereum/beacon-APIs/pull/552) `GET /eth/v1/validator/payload_attestation_data` added | | | | | | +| [#552](https://github.com/ethereum/beacon-APIs/pull/552) `POST /eth/v1/validator/duties/ptc/{epoch}` added | | | | | | +| [#552](https://github.com/ethereum/beacon-APIs/pull/552) `POST /eth/v1/beacon/execution_payload_bid` added | | | | | | +| [#552](https://github.com/ethereum/beacon-APIs/pull/552) `POST /eth/v1/beacon/execution_payload_envelope` added | | | | | | +| [#552](https://github.com/ethereum/beacon-APIs/pull/552) `POST /eth/v1/beacon/pool/payload_attestations` added | | | | | | +| [#552](https://github.com/ethereum/beacon-APIs/pull/552) `GET /eth/v4/validator/blocks/{slot}` added | | | | | | +| [#552](https://github.com/ethereum/beacon-APIs/pull/552) `POST /eth/v2/beacon/blocks` updated | | | | | | The Following are no longer in the Standard API, removed since the latest version. diff --git a/apis/beacon/execution_payload/bid.yaml b/apis/beacon/execution_payload/bid.yaml new file mode 100644 index 00000000..96dec67f --- /dev/null +++ b/apis/beacon/execution_payload/bid.yaml @@ -0,0 +1,41 @@ +post: + operationId: publishExecutionPayloadBid + summary: Publish signed execution payload bid + description: | + Instructs the beacon node to broadcast a signed execution payload bid to the beacon network, + to be gossiped for potential inclusion in block building. A success response indicates + that the bid passed gossip validation and was successfully broadcast onto the network. + tags: + - Beacon + requestBody: + description: "The `SignedExecutionPayloadBid` object to be broadcast." + 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: "The bid was validated successfully and has been broadcast." + content: + text/plain: + schema: + type: string + "400": + description: "The SignedExecutionPayloadBid object is invalid or failed gossip validation" + content: + application/json: + schema: + $ref: "../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage" + example: + code: 400 + message: "Invalid signed execution payload bid" + "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" diff --git a/apis/validator/execution_payload_bid.yaml b/apis/validator/execution_payload_bid.yaml new file mode 100644 index 00000000..b7f14b1a --- /dev/null +++ b/apis/validator/execution_payload_bid.yaml @@ -0,0 +1,69 @@ +get: + operationId: getExecutionPayloadBid + summary: Get execution payload bid + description: | + Retrieves execution payload bid for a given slot and builder. Depending on `Accept` header, it can be returned either as json or as bytes serialized by SSZ. + tags: + - Validator + parameters: + - name: slot + in: path + required: true + description: "Slot for which the execution payload bid is requested. Must be current slot or next slot." + schema: + $ref: '../../beacon-node-oapi.yaml#/components/schemas/Uint64' + - name: builder_index + in: path + required: true + description: "Index of the builder from which the execution payload bid is requested." + schema: + $ref: '../../beacon-node-oapi.yaml#/components/schemas/Uint64' + responses: + "200": + description: "Successful response" + headers: + Eth-Consensus-Version: + $ref: '../../beacon-node-oapi.yaml#/components/headers/Eth-Consensus-Version' + required: true + content: + application/json: + schema: + title: GetExecutionPayloadBidResponse + type: object + required: [data] + properties: + version: + type: string + enum: [gloas] + example: "gloas" + execution_optimistic: + $ref: "../../beacon-node-oapi.yaml#/components/schemas/ExecutionOptimistic" + finalized: + $ref: "../../beacon-node-oapi.yaml#/components/schemas/Finalized" + data: + $ref: "../../beacon-node-oapi.yaml#/components/schemas/Gloas.ExecutionPayloadBid" + application/octet-stream: + schema: + description: "SSZ serialized execution payload bid bytes. Use Accept header to choose this response type" + "400": + description: "The slot supplied could not be parsed or is invalid" + content: + application/json: + schema: + $ref: "../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage" + example: + code: 400 + message: "Invalid slot: must be current slot or next slot" + "404": + description: "Execution payload bid not available for the requested slot and builder" + content: + application/json: + schema: + $ref: "../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage" + example: + code: 404 + message: "Execution payload bid not available for slot and builder" + "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 e03840ba..28570bb3 100644 --- a/beacon-node-oapi.yaml +++ b/beacon-node-oapi.yaml @@ -104,6 +104,8 @@ paths: $ref: "./apis/beacon/blocks/blinded_blocks.v2.yaml" /eth/v2/beacon/blocks: $ref: "./apis/beacon/blocks/blocks.v2.yaml" + /eth/v1/beacon/execution_payload_bid: + $ref: "./apis/beacon/execution_payload/bid.yaml" /eth/v2/beacon/blocks/{block_id}: $ref: "./apis/beacon/blocks/block.v2.yaml" /eth/v1/beacon/blocks/{block_id}/root: @@ -206,6 +208,8 @@ paths: $ref: "./apis/validator/register_validator.yaml" /eth/v1/validator/liveness/{epoch}: $ref: "./apis/validator/liveness.yaml" + /eth/v1/validator/execution_payload_bid/{slot}/{builder_index}: + $ref: "./apis/validator/execution_payload_bid.yaml" /eth/v1/events: $ref: "./apis/eventstream/index.yaml" @@ -431,6 +435,10 @@ components: $ref: "./types/gloas/block.yaml#/Gloas/BeaconBlock" Gloas.SignedBeaconBlock: $ref: "./types/gloas/block.yaml#/Gloas/SignedBeaconBlock" + Gloas.ExecutionPayloadBid: + $ref: "./types/gloas/execution_payload_bid.yaml#/Gloas/ExecutionPayloadBid" + Gloas.SignedExecutionPayloadBid: + $ref: "./types/gloas/execution_payload_bid.yaml#/Gloas/SignedExecutionPayloadBid" Fulu.BlockContents: $ref: "./types/fulu/block_contents.yaml#/Fulu/BlockContents" Fulu.SignedBlockContents: diff --git a/wordlist.txt b/wordlist.txt index d4ac324c..d802300c 100644 --- a/wordlist.txt +++ b/wordlist.txt @@ -37,3 +37,4 @@ KZGProofs KZGCommitmentInclusionProof LMD fulu +gloas From fecb8414374f6b59162c9ede830f1888341a70cc Mon Sep 17 00:00:00 2001 From: shane-moore Date: Thu, 4 Sep 2025 19:13:06 -0700 Subject: [PATCH 03/42] epbs execution_payload_envelope get and post --- apis/beacon/execution_payload/envelope.yaml | 41 +++++++++++ .../validator/execution_payload_envelope.yaml | 71 +++++++++++++++++++ beacon-node-oapi.yaml | 8 +++ types/gloas/execution_payload_envelope.yaml | 45 ++++++++++++ 4 files changed, 165 insertions(+) create mode 100644 apis/beacon/execution_payload/envelope.yaml create mode 100644 apis/validator/execution_payload_envelope.yaml create mode 100644 types/gloas/execution_payload_envelope.yaml diff --git a/apis/beacon/execution_payload/envelope.yaml b/apis/beacon/execution_payload/envelope.yaml new file mode 100644 index 00000000..d4b8f2ed --- /dev/null +++ b/apis/beacon/execution_payload/envelope.yaml @@ -0,0 +1,41 @@ +post: + operationId: publishExecutionPayloadEnvelope + summary: Publish signed execution payload envelope + description: | + Instructs the beacon node to broadcast a signed execution payload envelope to the beacon network, + to be gossiped for payload validation. A success response (20x) indicates + that the envelope passed gossip validation and was successfully broadcast onto the network. + tags: + - Beacon + requestBody: + description: "The `SignedExecutionPayloadEnvelope` object to be broadcast." + required: true + content: + application/json: + schema: + $ref: "../../beacon-node-oapi.yaml#/components/schemas/Gloas.SignedExecutionPayloadEnvelope" + application/octet-stream: + schema: + description: "SSZ serialized SignedExecutionPayloadEnvelope bytes. Use Content-Type header to specify this format" + responses: + "200": + description: "The envelope was validated successfully and has been broadcast." + content: + text/plain: + schema: + type: string + "400": + description: "The SignedExecutionPayloadEnvelope object is invalid or failed gossip validation" + content: + application/json: + schema: + $ref: "../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage" + example: + code: 400 + message: "Invalid signed execution payload envelope" + "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" diff --git a/apis/validator/execution_payload_envelope.yaml b/apis/validator/execution_payload_envelope.yaml new file mode 100644 index 00000000..14a451a3 --- /dev/null +++ b/apis/validator/execution_payload_envelope.yaml @@ -0,0 +1,71 @@ +get: + operationId: getExecutionPayloadEnvelope + summary: Get execution payload envelope + description: | + Retrieves execution payload envelope for a given slot and builder. The envelope contains the full + execution payload along with associated metadata. Depending on `Accept` header, it can be returned + either as json or as bytes serialized by SSZ. + tags: + - Validator + parameters: + - name: slot + in: path + required: true + description: "Slot for which the execution payload envelope is requested." + schema: + $ref: '../../beacon-node-oapi.yaml#/components/schemas/Uint64' + - name: builder_index + in: path + required: true + description: "Index of the builder from which the execution payload envelope is requested." + schema: + $ref: '../../beacon-node-oapi.yaml#/components/schemas/Uint64' + responses: + "200": + description: "Successful response" + headers: + Eth-Consensus-Version: + $ref: '../../beacon-node-oapi.yaml#/components/headers/Eth-Consensus-Version' + required: true + content: + application/json: + schema: + title: GetExecutionPayloadEnvelopeResponse + type: object + required: [data] + properties: + version: + type: string + enum: [gloas] + example: "gloas" + execution_optimistic: + $ref: "../../beacon-node-oapi.yaml#/components/schemas/ExecutionOptimistic" + finalized: + $ref: "../../beacon-node-oapi.yaml#/components/schemas/Finalized" + data: + $ref: "../../beacon-node-oapi.yaml#/components/schemas/Gloas.ExecutionPayloadEnvelope" + application/octet-stream: + schema: + description: "SSZ serialized execution payload envelope bytes. Use Accept header to choose this response type" + "400": + description: "Invalid execution payload envelope request" + content: + application/json: + schema: + $ref: "../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage" + example: + code: 400 + message: "Invalid slot or builder_index parameter" + "404": + description: "Execution payload envelope not available for the requested slot and builder" + content: + application/json: + schema: + $ref: "../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage" + example: + code: 404 + message: "Execution payload envelope not available for slot and builder" + "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 28570bb3..5ef1fd82 100644 --- a/beacon-node-oapi.yaml +++ b/beacon-node-oapi.yaml @@ -106,6 +106,8 @@ paths: $ref: "./apis/beacon/blocks/blocks.v2.yaml" /eth/v1/beacon/execution_payload_bid: $ref: "./apis/beacon/execution_payload/bid.yaml" + /eth/v1/beacon/execution_payload_envelope: + $ref: "./apis/beacon/execution_payload/envelope.yaml" /eth/v2/beacon/blocks/{block_id}: $ref: "./apis/beacon/blocks/block.v2.yaml" /eth/v1/beacon/blocks/{block_id}/root: @@ -210,6 +212,8 @@ paths: $ref: "./apis/validator/liveness.yaml" /eth/v1/validator/execution_payload_bid/{slot}/{builder_index}: $ref: "./apis/validator/execution_payload_bid.yaml" + /eth/v1/validator/execution_payload_envelope/{slot}/{builder_index}: + $ref: "./apis/validator/execution_payload_envelope.yaml" /eth/v1/events: $ref: "./apis/eventstream/index.yaml" @@ -439,6 +443,10 @@ components: $ref: "./types/gloas/execution_payload_bid.yaml#/Gloas/ExecutionPayloadBid" Gloas.SignedExecutionPayloadBid: $ref: "./types/gloas/execution_payload_bid.yaml#/Gloas/SignedExecutionPayloadBid" + Gloas.ExecutionPayloadEnvelope: + $ref: "./types/gloas/execution_payload_envelope.yaml#/Gloas/ExecutionPayloadEnvelope" + Gloas.SignedExecutionPayloadEnvelope: + $ref: "./types/gloas/execution_payload_envelope.yaml#/Gloas/SignedExecutionPayloadEnvelope" Fulu.BlockContents: $ref: "./types/fulu/block_contents.yaml#/Fulu/BlockContents" Fulu.SignedBlockContents: diff --git a/types/gloas/execution_payload_envelope.yaml b/types/gloas/execution_payload_envelope.yaml new file mode 100644 index 00000000..8b74464c --- /dev/null +++ b/types/gloas/execution_payload_envelope.yaml @@ -0,0 +1,45 @@ +Gloas: + ExecutionPayloadEnvelope: + type: object + description: "The [ExecutionPayloadEnvelope](https://github.com/ethereum/consensus-specs/blob/master/specs/gloas/beacon-chain.md#executionpayloadenvelope) object from the CL gloas spec." + required: [payload, execution_requests, builder_index, beacon_block_root, slot, blob_kzg_commitments, state_root] + properties: + payload: + $ref: "../deneb/execution_payload.yaml#/Deneb/ExecutionPayload" + execution_requests: + $ref: "../electra/execution_requests.yaml#/Electra/ExecutionRequests" + builder_index: + allOf: + - $ref: "../primitive.yaml#/Uint64" + - description: "Index of the builder that created this execution payload" + beacon_block_root: + allOf: + - $ref: "../primitive.yaml#/Root" + - description: "Root of the beacon block for this payload" + slot: + allOf: + - $ref: "../primitive.yaml#/Uint64" + - description: "Slot number for this execution payload" + blob_kzg_commitments: + type: array + items: + $ref: "../primitive.yaml#/KZGCommitment" + minItems: 0 + maxItems: 4096 + description: "KZG commitments for the blobs included in this execution payload" + state_root: + allOf: + - $ref: "../primitive.yaml#/Root" + - description: "Beacon state root after executing this payload" + + SignedExecutionPayloadEnvelope: + type: object + description: "The [SignedExecutionPayloadEnvelope](https://github.com/ethereum/consensus-specs/blob/master/specs/gloas/beacon-chain.md#signedexecutionpayloadenvelope) object from the CL gloas spec." + required: [message, signature] + properties: + message: + $ref: "#/Gloas/ExecutionPayloadEnvelope" + signature: + allOf: + - $ref: "../primitive.yaml#/BLSSignature" + - description: "BLS signature of the execution payload envelope" From 740bf109db29dffe75e87425fd6cd5c833ea10c3 Mon Sep 17 00:00:00 2001 From: shane-moore Date: Fri, 5 Sep 2025 11:17:43 -0700 Subject: [PATCH 04/42] new epbs ptc assignment POST --- apis/validator/duties/ptc.yaml | 71 ++++++++++++++++++++++++++++++++++ beacon-node-oapi.yaml | 4 ++ types/duty.yaml | 13 +++++++ 3 files changed, 88 insertions(+) create mode 100644 apis/validator/duties/ptc.yaml diff --git a/apis/validator/duties/ptc.yaml b/apis/validator/duties/ptc.yaml new file mode 100644 index 00000000..c4708b78 --- /dev/null +++ b/apis/validator/duties/ptc.yaml @@ -0,0 +1,71 @@ +post: + tags: + - Validator + summary: "Get PTC duties" + operationId: "getPtcDuties" + description: "Requests the beacon node to provide a set of Payload Timeliness Committee (PTC) duties, + which should be performed by validators, for a particular epoch. + + Duties should only need to be checked once per epoch, + however a chain reorganization (of > MIN_SEED_LOOKAHEAD epochs) could occur, resulting in a change of duties. For full safety, + you should monitor head events and confirm the dependent root in this response matches: + + - event.previous_duty_dependent_root when `compute_epoch_at_slot(event.slot) == epoch` + + - event.current_duty_dependent_root when `compute_epoch_at_slot(event.slot) + 1 == epoch` + + - event.block otherwise + + + The dependent_root value is `get_block_root_at_slot(state, compute_start_slot_at_epoch(epoch - 1) - 1)` + or the genesis block root in the case of underflow." + parameters: + - name: epoch + description: "Should only be allowed 1 epoch ahead" + in: path + required: true + schema: + $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Uint64" + requestBody: + description: "An array of the validator indices for which to obtain the duties." + required: true + content: + application/json: + schema: + title: GetPtcDutiesBody + type: array + minItems: 1 + uniqueItems: true + items: + $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Uint64" + responses: + "200": + description: Success response + content: + application/json: + schema: + title: GetPtcDutiesResponse + type: object + required: [dependent_root, execution_optimistic, data] + properties: + dependent_root: + $ref: "../../../beacon-node-oapi.yaml#/components/schemas/DependentRoot" + execution_optimistic: + $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ExecutionOptimistic" + data: + type: array + items: + $ref: '../../../beacon-node-oapi.yaml#/components/schemas/PtcDuty' + "400": + description: "Invalid epoch or index" + content: + application/json: + schema: + $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage" + example: + code: 400 + message: "Invalid epoch: -2" + "500": + $ref: "../../../beacon-node-oapi.yaml#/components/responses/InternalError" + "503": + $ref: "../../../beacon-node-oapi.yaml#/components/responses/CurrentlySyncing" diff --git a/beacon-node-oapi.yaml b/beacon-node-oapi.yaml index 5ef1fd82..2477ea00 100644 --- a/beacon-node-oapi.yaml +++ b/beacon-node-oapi.yaml @@ -184,6 +184,8 @@ paths: $ref: "./apis/validator/duties/proposer.yaml" /eth/v1/validator/duties/sync/{epoch}: $ref: "./apis/validator/duties/sync.yaml" + /eth/v1/validator/duties/ptc/{epoch}: + $ref: "./apis/validator/duties/ptc.yaml" /eth/v3/validator/blocks/{slot}: $ref: "./apis/validator/block.v3.yaml" /eth/v1/validator/attestation_data: @@ -237,6 +239,8 @@ components: $ref: './types/duty.yaml#/AttesterDuty' ProposerDuty: $ref: './types/duty.yaml#/ProposerDuty' + PtcDuty: + $ref: './types/duty.yaml#/PtcDuty' Altair.SyncDuty: $ref: './types/duty.yaml#/Altair/SyncDuty' BeaconCommitteeSelection: diff --git a/types/duty.yaml b/types/duty.yaml index f9ff9314..eae60438 100644 --- a/types/duty.yaml +++ b/types/duty.yaml @@ -52,3 +52,16 @@ Altair: minItems: 1 items: $ref: './primitive.yaml#/Uint64' + +PtcDuty: + type: object + required: [pubkey, validator_index, slot] + properties: + pubkey: + $ref: './primitive.yaml#/Pubkey' + validator_index: + $ref: "./primitive.yaml#/Uint64" + description: "Index of validator in validator registry." + slot: + $ref: "./primitive.yaml#/Uint64" + description: "The slot at which the validator must perform PTC duties." From e60562504ccc61205148bc8d9d93086f758450e0 Mon Sep 17 00:00:00 2001 From: shane-moore Date: Fri, 5 Sep 2025 12:44:24 -0700 Subject: [PATCH 05/42] new epbs payload_attestations get and post --- apis/beacon/pool/payload_attestations.yaml | 83 ++++++++++++++++++++ apis/validator/duties/ptc.yaml | 1 + apis/validator/payload_attestation_data.yaml | 43 ++++++++++ beacon-node-oapi.yaml | 10 +++ types/gloas/block.yaml | 2 +- types/gloas/payload_attestation.yaml | 48 +++++++++++ types/gloas/payload_attestations.yaml | 28 ------- 7 files changed, 186 insertions(+), 29 deletions(-) create mode 100644 apis/beacon/pool/payload_attestations.yaml create mode 100644 apis/validator/payload_attestation_data.yaml create mode 100644 types/gloas/payload_attestation.yaml delete mode 100644 types/gloas/payload_attestations.yaml diff --git a/apis/beacon/pool/payload_attestations.yaml b/apis/beacon/pool/payload_attestations.yaml new file mode 100644 index 00000000..3026a9d0 --- /dev/null +++ b/apis/beacon/pool/payload_attestations.yaml @@ -0,0 +1,83 @@ +get: + operationId: getPoolPayloadAttestations + summary: Get payload attestations from operations pool + description: Retrieves payload attestations known by the node but not necessarily incorporated into any block + parameters: + - name: slot + in: query + required: false + schema: + $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Uint64' + tags: + - Beacon + responses: + "200": + description: Successful response + content: + application/json: + schema: + title: GetPoolPayloadAttestationsResponse + type: object + required: [version, data] + properties: + version: + type: string + enum: [gloas] + example: "gloas" + data: + type: array + items: + $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Gloas.PayloadAttestationMessage' + "400": + description: "The slot could not be parsed" + content: + application/json: + schema: + $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage" + example: + code: 400 + message: "Invalid slot parameter" + "500": + $ref: '../../../beacon-node-oapi.yaml#/components/responses/InternalError' + +post: + operationId: submitPayloadAttestationMessage + summary: Submit payload attestation message + description: | + Submits a payload attestation message to the beacon node. + + The beacon node will validate the payload attestation message according to the gossip validation rules + and, if valid, store it in the pool and broadcast it globally to the network. + + A success response indicates that the payload attestation message passed validation and was + successfully stored and broadcast. + tags: + - Beacon + - ValidatorRequiredApi + requestBody: + description: "The PayloadAttestationMessage object to be submitted." + required: true + content: + application/json: + schema: + $ref: "../../beacon-node-oapi.yaml#/components/schemas/Gloas.PayloadAttestationMessage" + application/octet-stream: + schema: + description: "SSZ serialized PayloadAttestationMessage bytes. Use Content-Type header to indicate that SSZ data is contained in the request body." + responses: + "200": + description: "The payload attestation message was stored in the pool and has been broadcast." + content: + text/plain: + schema: + type: string + "400": + description: "The PayloadAttestationMessage object is invalid or failed gossip validation" + content: + application/json: + schema: + $ref: "../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage" + "415": + $ref: "../../beacon-node-oapi.yaml#/components/responses/UnsupportedMediaType" + "500": + $ref: "../../beacon-node-oapi.yaml#/components/responses/InternalError" diff --git a/apis/validator/duties/ptc.yaml b/apis/validator/duties/ptc.yaml index c4708b78..002936ac 100644 --- a/apis/validator/duties/ptc.yaml +++ b/apis/validator/duties/ptc.yaml @@ -1,6 +1,7 @@ post: tags: - Validator + - ValidatorRequiredApi summary: "Get PTC duties" operationId: "getPtcDuties" description: "Requests the beacon node to provide a set of Payload Timeliness Committee (PTC) duties, diff --git a/apis/validator/payload_attestation_data.yaml b/apis/validator/payload_attestation_data.yaml new file mode 100644 index 00000000..0932dc2e --- /dev/null +++ b/apis/validator/payload_attestation_data.yaml @@ -0,0 +1,43 @@ +get: + tags: + - ValidatorRequiredApi + - Validator + operationId: "producePayloadAttestationData" + summary: "Produce payload attestation data" + description: | + Requests that the beacon node produce a PayloadAttestationData. + + This endpoint is used by PTC validators to obtain the data structure they need to attest to + regarding payload presence and blob data availability for a specific slot. + + A 503 error must be returned if the beacon node is currently syncing. + parameters: + - name: slot + in: query + required: true + description: "The slot for which payload attestation data should be created." + schema: + $ref: ../../beacon-node-oapi.yaml#/components/schemas/Uint64 + responses: + "200": + description: "Success response" + content: + application/json: + schema: + title: ProducePayloadAttestationDataResponse + type: object + required: [data] + properties: + data: + $ref: "../../beacon-node-oapi.yaml#/components/schemas/Gloas.PayloadAttestationData" + application/octet-stream: + schema: + description: "SSZ serialized PayloadAttestationData bytes. Use Accept header to choose this response type" + "400": + $ref: '../../beacon-node-oapi.yaml#/components/responses/InvalidRequest' + "406": + $ref: '../../beacon-node-oapi.yaml#/components/responses/NotAcceptable' + "500": + $ref: "../../beacon-node-oapi.yaml#/components/responses/InternalError" + "503": + $ref: "../../beacon-node-oapi.yaml#/components/responses/CurrentlySyncing" diff --git a/beacon-node-oapi.yaml b/beacon-node-oapi.yaml index 2477ea00..a917b743 100644 --- a/beacon-node-oapi.yaml +++ b/beacon-node-oapi.yaml @@ -138,6 +138,8 @@ paths: $ref: "./apis/beacon/light_client/optimistic_update.yaml" /eth/v2/beacon/pool/attestations: $ref: "./apis/beacon/pool/attestations.v2.yaml" + /eth/v1/beacon/pool/payload_attestations: + $ref: "./apis/beacon/pool/payload_attestations.yaml" /eth/v2/beacon/pool/attester_slashings: $ref: "./apis/beacon/pool/attester_slashings.v2.yaml" /eth/v1/beacon/pool/proposer_slashings: @@ -190,6 +192,8 @@ paths: $ref: "./apis/validator/block.v3.yaml" /eth/v1/validator/attestation_data: $ref: "./apis/validator/attestation_data.yaml" + /eth/v1/validator/payload_attestation_data: + $ref: "./apis/validator/payload_attestation_data.yaml" /eth/v2/validator/aggregate_attestation: $ref: "./apis/validator/aggregate_attestation.v2.yaml" /eth/v2/validator/aggregate_and_proofs: @@ -451,6 +455,12 @@ components: $ref: "./types/gloas/execution_payload_envelope.yaml#/Gloas/ExecutionPayloadEnvelope" Gloas.SignedExecutionPayloadEnvelope: $ref: "./types/gloas/execution_payload_envelope.yaml#/Gloas/SignedExecutionPayloadEnvelope" + Gloas.PayloadAttestationData: + $ref: "./types/gloas/payload_attestation.yaml#/Gloas/PayloadAttestationData" + Gloas.PayloadAttestation: + $ref: "./types/gloas/payload_attestation.yaml#/Gloas/PayloadAttestation" + Gloas.PayloadAttestationMessage: + $ref: "./types/gloas/payload_attestation.yaml#/Gloas/PayloadAttestationMessage" Fulu.BlockContents: $ref: "./types/fulu/block_contents.yaml#/Fulu/BlockContents" Fulu.SignedBlockContents: diff --git a/types/gloas/block.yaml b/types/gloas/block.yaml index defc7bfd..a849a691 100644 --- a/types/gloas/block.yaml +++ b/types/gloas/block.yaml @@ -52,7 +52,7 @@ Gloas: type: array description: "Array of payload attestations from gloas." items: - $ref: "./payload_attestations.yaml#/Gloas/PayloadAttestation" + $ref: "./payload_attestation.yaml#/Gloas/PayloadAttestation" minItems: 0 maxItems: 4 diff --git a/types/gloas/payload_attestation.yaml b/types/gloas/payload_attestation.yaml new file mode 100644 index 00000000..435a5832 --- /dev/null +++ b/types/gloas/payload_attestation.yaml @@ -0,0 +1,48 @@ +Gloas: + PayloadAttestationData: + type: object + description: "The [`PayloadAttestationData`](https://github.com/ethereum/consensus-specs/blob/master/specs/gloas/beacon-chain.md#payloadattestationdata) object from the CL Gloas spec." + required: [beacon_block_root, slot, payload_present, blob_data_available] + properties: + beacon_block_root: + allOf: + - $ref: "../primitive.yaml#/Root" + - description: "Hash tree root of the beacon block associated with this ptc attestation" + slot: + allOf: + - $ref: "../primitive.yaml#/Uint64" + - description: "The slot for which the payload attestation is being made" + payload_present: + type: boolean + description: "True if a SignedExecutionPayloadEnvelope has been seen referencing this block" + blob_data_available: + type: boolean + description: "True if blob data is available for this block" + + PayloadAttestation: + type: object + description: "The [PayloadAttestation](https://github.com/ethereum/consensus-specs/blob/master/specs/gloas/beacon-chain.md#payloadattestation) object from the CL gloas spec." + required: [aggregation_bits, data, signature] + properties: + aggregation_bits: + $ref: "../primitive.yaml#/BitList" + data: + $ref: "#/Gloas/PayloadAttestationData" + signature: + $ref: "../primitive.yaml#/Signature" + + PayloadAttestationMessage: + type: object + description: "The [`PayloadAttestationMessage`](https://github.com/ethereum/consensus-specs/blob/master/specs/gloas/beacon-chain.md#payloadattestationmessage) object from the CL Gloas spec." + required: [validator_index, data, signature] + properties: + validator_index: + allOf: + - $ref: "../primitive.yaml#/Uint64" + - description: "Index of the validator submitting the payload attestation" + data: + $ref: "#/Gloas/PayloadAttestationData" + signature: + allOf: + - $ref: "../primitive.yaml#/Signature" + - description: "BLS signature of the payload attestation data" diff --git a/types/gloas/payload_attestations.yaml b/types/gloas/payload_attestations.yaml deleted file mode 100644 index 80f654a0..00000000 --- a/types/gloas/payload_attestations.yaml +++ /dev/null @@ -1,28 +0,0 @@ -Gloas: - PayloadAttestation: - type: object - description: "The [PayloadAttestation](https://github.com/ethereum/consensus-specs/blob/master/specs/gloas/beacon-chain.md#payloadattestation) object from the CL gloas spec." - required: [aggregation_bits, data, signature] - properties: - aggregation_bits: - $ref: "../primitive.yaml#/BitList" - data: - $ref: "#/Gloas/PayloadAttestationData" - signature: - $ref: "../primitive.yaml#/Signature" - - PayloadAttestationData: - type: object - description: "The [PayloadAttestationData](https://github.com/ethereum/consensus-specs/blob/master/specs/gloas/beacon-chain.md#payloadattestationdata) object from the CL gloas spec." - required: [beacon_block_root, slot, payload_present, blob_data_available] - properties: - beacon_block_root: - $ref: "../primitive.yaml#/Root" - slot: - $ref: "../primitive.yaml#/Uint64" - payload_present: - type: boolean - description: "Whether the execution payload is present" - blob_data_available: - type: boolean - description: "Whether blob data is available" From 3ad50a6229a8247d6290edfb9dd079707a78aeb8 Mon Sep 17 00:00:00 2001 From: shane-moore Date: Fri, 5 Sep 2025 14:36:14 -0700 Subject: [PATCH 06/42] small fixes --- apis/beacon/execution_payload/bid.yaml | 10 +++++----- apis/beacon/execution_payload/envelope.yaml | 10 +++++----- apis/beacon/pool/payload_attestations.yaml | 14 +++++++------- apis/validator/duties/ptc.yaml | 2 +- apis/validator/execution_payload_bid.yaml | 9 ++++----- apis/validator/execution_payload_envelope.yaml | 9 ++++----- apis/validator/payload_attestation_data.yaml | 6 +++--- types/gloas/execution_payload_envelope.yaml | 2 +- 8 files changed, 30 insertions(+), 32 deletions(-) diff --git a/apis/beacon/execution_payload/bid.yaml b/apis/beacon/execution_payload/bid.yaml index 96dec67f..27acab68 100644 --- a/apis/beacon/execution_payload/bid.yaml +++ b/apis/beacon/execution_payload/bid.yaml @@ -13,7 +13,7 @@ post: content: application/json: schema: - $ref: "../../beacon-node-oapi.yaml#/components/schemas/Gloas.SignedExecutionPayloadBid" + $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" @@ -29,13 +29,13 @@ post: content: application/json: schema: - $ref: "../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage" + $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage" example: code: 400 message: "Invalid signed execution payload bid" "406": - $ref: "../../beacon-node-oapi.yaml#/components/responses/NotAcceptable" + $ref: "../../../beacon-node-oapi.yaml#/components/responses/NotAcceptable" "415": - $ref: "../../beacon-node-oapi.yaml#/components/responses/UnsupportedMediaType" + $ref: "../../../beacon-node-oapi.yaml#/components/responses/UnsupportedMediaType" "500": - $ref: "../../beacon-node-oapi.yaml#/components/responses/InternalError" + $ref: "../../../beacon-node-oapi.yaml#/components/responses/InternalError" diff --git a/apis/beacon/execution_payload/envelope.yaml b/apis/beacon/execution_payload/envelope.yaml index d4b8f2ed..6c5c1228 100644 --- a/apis/beacon/execution_payload/envelope.yaml +++ b/apis/beacon/execution_payload/envelope.yaml @@ -13,7 +13,7 @@ post: content: application/json: schema: - $ref: "../../beacon-node-oapi.yaml#/components/schemas/Gloas.SignedExecutionPayloadEnvelope" + $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Gloas.SignedExecutionPayloadEnvelope" application/octet-stream: schema: description: "SSZ serialized SignedExecutionPayloadEnvelope bytes. Use Content-Type header to specify this format" @@ -29,13 +29,13 @@ post: content: application/json: schema: - $ref: "../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage" + $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage" example: code: 400 message: "Invalid signed execution payload envelope" "406": - $ref: "../../beacon-node-oapi.yaml#/components/responses/NotAcceptable" + $ref: "../../../beacon-node-oapi.yaml#/components/responses/NotAcceptable" "415": - $ref: "../../beacon-node-oapi.yaml#/components/responses/UnsupportedMediaType" + $ref: "../../../beacon-node-oapi.yaml#/components/responses/UnsupportedMediaType" "500": - $ref: "../../beacon-node-oapi.yaml#/components/responses/InternalError" + $ref: "../../../beacon-node-oapi.yaml#/components/responses/InternalError" diff --git a/apis/beacon/pool/payload_attestations.yaml b/apis/beacon/pool/payload_attestations.yaml index 3026a9d0..3bcc47cb 100644 --- a/apis/beacon/pool/payload_attestations.yaml +++ b/apis/beacon/pool/payload_attestations.yaml @@ -7,7 +7,7 @@ get: in: query required: false schema: - $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Uint64' + $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Uint64" tags: - Beacon responses: @@ -27,7 +27,7 @@ get: data: type: array items: - $ref: '../../../beacon-node-oapi.yaml#/components/schemas/Gloas.PayloadAttestationMessage' + $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Gloas.PayloadAttestationMessage" "400": description: "The slot could not be parsed" content: @@ -38,7 +38,7 @@ get: code: 400 message: "Invalid slot parameter" "500": - $ref: '../../../beacon-node-oapi.yaml#/components/responses/InternalError' + $ref: "../../../beacon-node-oapi.yaml#/components/responses/InternalError" post: operationId: submitPayloadAttestationMessage @@ -60,7 +60,7 @@ post: content: application/json: schema: - $ref: "../../beacon-node-oapi.yaml#/components/schemas/Gloas.PayloadAttestationMessage" + $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Gloas.PayloadAttestationMessage" application/octet-stream: schema: description: "SSZ serialized PayloadAttestationMessage bytes. Use Content-Type header to indicate that SSZ data is contained in the request body." @@ -76,8 +76,8 @@ post: content: application/json: schema: - $ref: "../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage" + $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage" "415": - $ref: "../../beacon-node-oapi.yaml#/components/responses/UnsupportedMediaType" + $ref: "../../../beacon-node-oapi.yaml#/components/responses/UnsupportedMediaType" "500": - $ref: "../../beacon-node-oapi.yaml#/components/responses/InternalError" + $ref: "../../../beacon-node-oapi.yaml#/components/responses/InternalError" diff --git a/apis/validator/duties/ptc.yaml b/apis/validator/duties/ptc.yaml index 002936ac..c8691f59 100644 --- a/apis/validator/duties/ptc.yaml +++ b/apis/validator/duties/ptc.yaml @@ -56,7 +56,7 @@ post: data: type: array items: - $ref: '../../../beacon-node-oapi.yaml#/components/schemas/PtcDuty' + $ref: "../../../beacon-node-oapi.yaml#/components/schemas/PtcDuty" "400": description: "Invalid epoch or index" content: diff --git a/apis/validator/execution_payload_bid.yaml b/apis/validator/execution_payload_bid.yaml index b7f14b1a..34901a33 100644 --- a/apis/validator/execution_payload_bid.yaml +++ b/apis/validator/execution_payload_bid.yaml @@ -11,26 +11,25 @@ get: required: true description: "Slot for which the execution payload bid is requested. Must be current slot or next slot." schema: - $ref: '../../beacon-node-oapi.yaml#/components/schemas/Uint64' + $ref: "../../beacon-node-oapi.yaml#/components/schemas/Uint64" - name: builder_index in: path required: true description: "Index of the builder from which the execution payload bid is requested." schema: - $ref: '../../beacon-node-oapi.yaml#/components/schemas/Uint64' + $ref: "../../beacon-node-oapi.yaml#/components/schemas/Uint64" responses: "200": description: "Successful response" headers: Eth-Consensus-Version: - $ref: '../../beacon-node-oapi.yaml#/components/headers/Eth-Consensus-Version' - required: true + $ref: "../../beacon-node-oapi.yaml#/components/headers/Eth-Consensus-Version" content: application/json: schema: title: GetExecutionPayloadBidResponse type: object - required: [data] + required: [version, execution_optimistic, finalized, data] properties: version: type: string diff --git a/apis/validator/execution_payload_envelope.yaml b/apis/validator/execution_payload_envelope.yaml index 14a451a3..d2c86f02 100644 --- a/apis/validator/execution_payload_envelope.yaml +++ b/apis/validator/execution_payload_envelope.yaml @@ -13,26 +13,25 @@ get: required: true description: "Slot for which the execution payload envelope is requested." schema: - $ref: '../../beacon-node-oapi.yaml#/components/schemas/Uint64' + $ref: "../../beacon-node-oapi.yaml#/components/schemas/Uint64" - name: builder_index in: path required: true description: "Index of the builder from which the execution payload envelope is requested." schema: - $ref: '../../beacon-node-oapi.yaml#/components/schemas/Uint64' + $ref: "../../beacon-node-oapi.yaml#/components/schemas/Uint64" responses: "200": description: "Successful response" headers: Eth-Consensus-Version: - $ref: '../../beacon-node-oapi.yaml#/components/headers/Eth-Consensus-Version' - required: true + $ref: "../../beacon-node-oapi.yaml#/components/headers/Eth-Consensus-Version" content: application/json: schema: title: GetExecutionPayloadEnvelopeResponse type: object - required: [data] + required: [version, execution_optimistic, finalized, data] properties: version: type: string diff --git a/apis/validator/payload_attestation_data.yaml b/apis/validator/payload_attestation_data.yaml index 0932dc2e..e13973b6 100644 --- a/apis/validator/payload_attestation_data.yaml +++ b/apis/validator/payload_attestation_data.yaml @@ -17,7 +17,7 @@ get: required: true description: "The slot for which payload attestation data should be created." schema: - $ref: ../../beacon-node-oapi.yaml#/components/schemas/Uint64 + $ref: "../../beacon-node-oapi.yaml#/components/schemas/Uint64" responses: "200": description: "Success response" @@ -34,9 +34,9 @@ get: schema: description: "SSZ serialized PayloadAttestationData bytes. Use Accept header to choose this response type" "400": - $ref: '../../beacon-node-oapi.yaml#/components/responses/InvalidRequest' + $ref: "../../beacon-node-oapi.yaml#/components/responses/InvalidRequest" "406": - $ref: '../../beacon-node-oapi.yaml#/components/responses/NotAcceptable' + $ref: "../../beacon-node-oapi.yaml#/components/responses/NotAcceptable" "500": $ref: "../../beacon-node-oapi.yaml#/components/responses/InternalError" "503": diff --git a/types/gloas/execution_payload_envelope.yaml b/types/gloas/execution_payload_envelope.yaml index 8b74464c..de6d3431 100644 --- a/types/gloas/execution_payload_envelope.yaml +++ b/types/gloas/execution_payload_envelope.yaml @@ -41,5 +41,5 @@ Gloas: $ref: "#/Gloas/ExecutionPayloadEnvelope" signature: allOf: - - $ref: "../primitive.yaml#/BLSSignature" + - $ref: "../primitive.yaml#/Signature" - description: "BLS signature of the execution payload envelope" From f5dca29babe9b55a16a25dc3dd85141cbbaaa8aa Mon Sep 17 00:00:00 2001 From: shane-moore Date: Fri, 5 Sep 2025 15:22:53 -0700 Subject: [PATCH 07/42] epbs documentation updates --- apis/validator/attestation_data.yaml | 4 +-- validator-flow.md | 41 ++++++++++++++++++++++++++-- 2 files changed, 41 insertions(+), 4 deletions(-) diff --git a/apis/validator/attestation_data.yaml b/apis/validator/attestation_data.yaml index 0b62f277..56f12835 100644 --- a/apis/validator/attestation_data.yaml +++ b/apis/validator/attestation_data.yaml @@ -6,7 +6,7 @@ get: summary: "Produce an attestation data" description: | Requests that the beacon node produce an AttestationData. For `slot`s in - Electra and later, this AttestationData must have a `committee_index` of 0. + Electra and Fulu, this AttestationData must have a `committee_index` of 0. In Gloas, this `committee_index` field is repurposed to signal payload status: 0 if the execution payload is not present in the canonical chain (EMPTY), or 1 if the payload is present (FULL). For current slot attestations, always use 0. A 503 error must be returned if the block identified by the response `beacon_block_root` is optimistic (i.e. the attestation attests to a block @@ -22,7 +22,7 @@ get: in: query description: | The committee index for which an attestation data should be created. For `slot`s in - Electra and later, this parameter MAY always be set to 0. + Electra and Fulu, this parameter MAY always be set to 0. In Gloas, it signals payload status: 0 for EMPTY payload status, 1 for FULL payload status. required: true schema: $ref: "../../beacon-node-oapi.yaml#/components/schemas/Uint64" diff --git a/validator-flow.md b/validator-flow.md index 37120fed..86eddc3b 100644 --- a/validator-flow.md +++ b/validator-flow.md @@ -36,15 +36,52 @@ Attesting: been assigned to. If any validators in the committee are aggregators, set `is_aggregator` to `True`, 2. Wait for new BeaconBlock for the assigned slot (either stream updates or poll) - - Max wait: `SECONDS_PER_SLOT / 3` seconds into the assigned slot + - Max wait: `SECONDS_PER_SLOT / 4` seconds into the assigned slot 3. [Fetch AttestationData](#/ValidatorRequiredApi/produceAttestationData) 4. [Submit Attestation](#/ValidatorRequiredApi/submitPoolAttestations) (AttestationData + aggregation bits) - Aggregation bits are `Bitlist` with length of committee (received in AttesterDuty) with bit on position `validator_committee_index` (see AttesterDuty) set to true 5. If aggregator: - - Wait for `SECONDS_PER_SLOT * 2 / 3` seconds into the assigned slot + - Wait for `SECONDS_PER_SLOT / 2` seconds into the assigned slot - [Fetch aggregated Attestation](#/ValidatorRequiredApi/getAggregatedAttestation) from Beacon Node you've subscribed to your subnet - [Publish SignedAggregateAndProofs](#/ValidatorRequiredApi/publishAggregateAndProofs) Monitor chain block reorganization events (TBD) as they could change attesters and aggregators. If reorg is detected, ask for new attester duties and proceed from 1.. + +### PTC Attesting + +On start of every epoch, validator should [fetch PTC duties](#/Validator/getPtcDuties) for epoch + 1. +Result are array of objects with validator index and assigned slot for payload timeliness committee participation. + +PTC Attesting: +1. Wait for new BeaconBlock for the assigned slot + - Max wait: `SECONDS_PER_SLOT / 4` seconds into the assigned slot +2. [Fetch PayloadAttestationData](#/ValidatorRequiredApi/producePayloadAttestationData) for the assigned slot +3. Sign PayloadAttestationData to create PayloadAttestationMessage +4. [Submit PayloadAttestationMessage](#/ValidatorRequiredApi/submitPayloadAttestationMessage) + - Must be submitted by `3/4` of slot duration (`PAYLOAD_ATTESTATION_DUE_BPS` = 75% of slot) + - Attestation indicates whether execution payload envelope has been seen for the block and if blobs were received + +Monitor chain block reorganization events (TBD) as they could change PTC assignments. +If reorg is detected, ask for new PTC duties and proceed from 1.. + +### Builder (Optional) + +Validators may optionally act as builders to submit execution payload bids for block inclusion. +This requires registering with builder-specific withdrawal credentials (`BUILDER_WITHDRAWAL_PREFIX`). + +Building: +1. [Fetch ExecutionPayloadBid](#/Validator/getExecutionPayloadBid) from beacon node + - Beacon node obtains payload via `engine_getPayload` call to execution client +2. Cache fields required to form an [ExecutionPayloadEnvelope](https://github.com/ethereum/consensus-specs/blob/master/specs/gloas/beacon-chain.md#executionpayloadenvelope) +2. Sign ExecutionPayloadBid to create SignedExecutionPayloadBid +3. [Submit SignedExecutionPayloadBid](#/Beacon/publishExecutionPayloadBid) to network for proposer consideration +4. If bid is selected by proposer in their block: + - [Fetch ExecutionPayloadEnvelope](#/Validator/getExecutionPayloadEnvelope) from beacon node + - Sign envelope and [submit SignedExecutionPayloadEnvelope](#/Beacon/publishExecutionPayloadEnvelope) + - Must submit early enough for PTC attestation by `3/4` of slot duration + +Monitor for block proposals containing your bid to trigger envelope release. + + From d1c62fbcf8ff64c3b3c83f1ed0e8362a267d5593 Mon Sep 17 00:00:00 2001 From: shane-moore Date: Thu, 11 Sep 2025 15:46:45 -0700 Subject: [PATCH 08/42] updates per pr review --- apis/validator/attestation_data.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apis/validator/attestation_data.yaml b/apis/validator/attestation_data.yaml index 56f12835..b25f71e1 100644 --- a/apis/validator/attestation_data.yaml +++ b/apis/validator/attestation_data.yaml @@ -6,7 +6,7 @@ get: summary: "Produce an attestation data" description: | Requests that the beacon node produce an AttestationData. For `slot`s in - Electra and Fulu, this AttestationData must have a `committee_index` of 0. In Gloas, this `committee_index` field is repurposed to signal payload status: 0 if the execution payload is not present in the canonical chain (EMPTY), or 1 if the payload is present (FULL). For current slot attestations, always use 0. + Electra and Fulu, this AttestationData must have a `committee_index` of 0. In Gloas, this `committee_index` field is repurposed to signal payload status: 0 if the execution payload is not present in the canonical chain (EMPTY), or 1 if the payload is present (FULL). For current slot attestations, which means the head block root is a block proposed in the same slot as the AttestationData.slot, always use 0. A 503 error must be returned if the block identified by the response `beacon_block_root` is optimistic (i.e. the attestation attests to a block From cd77f62fa6775230d2975a12ea55bbd2c952abae Mon Sep 17 00:00:00 2001 From: shane-moore Date: Fri, 12 Sep 2025 09:08:04 -0700 Subject: [PATCH 09/42] add produceBlockV4 endpoint --- apis/validator/block.v3.yaml | 14 ++--- apis/validator/block.v4.yaml | 111 +++++++++++++++++++++++++++++++++++ beacon-node-oapi.yaml | 13 ++-- 3 files changed, 125 insertions(+), 13 deletions(-) create mode 100644 apis/validator/block.v4.yaml diff --git a/apis/validator/block.v3.yaml b/apis/validator/block.v3.yaml index 67753872..71a8e96f 100644 --- a/apis/validator/block.v3.yaml +++ b/apis/validator/block.v3.yaml @@ -5,16 +5,16 @@ get: operationId: "produceBlockV3" summary: "Produce a new block, without signature." description: | - Requests a beacon node to produce a valid block, which can then be signed by a validator. + Requests a beacon node to produce a valid block, which can then be signed by a validator. The + returned block may be blinded or unblinded, depending on the current state of the network as + decided by the execution and beacon nodes. - 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. For pre-Gloas forks, the returned block may be blinded or unblinded, depending on the current - state of the network as decided by the execution and beacon nodes. The beacon node returns an - unblinded block if it obtains the execution payload from its paired execution node, or a - blinded block if it obtains the execution payload header from an MEV relay. + The beacon node must return an unblinded block if it obtains the execution payload from its + paired execution node. It must only return a blinded block if it obtains the execution payload + header from an MEV relay. Metadata in the response indicates the type of block produced, and the supported types of block - will be added to as forks progress. + are for all pre-Gloas forks. This endpoint is not forwards compatible after the Fulu fork. parameters: - name: slot in: path diff --git a/apis/validator/block.v4.yaml b/apis/validator/block.v4.yaml new file mode 100644 index 00000000..3c2dfb9a --- /dev/null +++ b/apis/validator/block.v4.yaml @@ -0,0 +1,111 @@ +get: + tags: + - ValidatorRequiredApi + - Validator + operationId: "produceBlockV4" + summary: "Produce a new block, without signature." + description: | + Requests a beacon node to produce a valid block, which can then be signed by a validator. + + 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. + 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: builder_boost_factor + in: query + required: false + description: | + Percentage multiplier to apply to the builder's payload value when choosing between a + builder payload header and payload from the paired execution node. This parameter is only + relevant if the beacon node is connected to a builder, deems it safe to produce a builder + payload, and receives valid responses from both the builder endpoint _and_ 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 full (unblinded) block containing the execution node payload. + * otherwise, return a blinded block containing the builder payload header. + + 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 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 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" + 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' + content: + application/json: + schema: + title: "ProduceBlockV4Response" + type: object + required: [version, data, consensus_block_value] + properties: + version: + type: string + enum: [gloas] + example: "gloas" + consensus_block_value: + type: string + example: "12345" + description: "Consensus rewards for this block in Wei" + data: + $ref: "../../beacon-node-oapi.yaml#/components/schemas/Gloas.BeaconBlock" + 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`." + "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" + "500": + $ref: '../../beacon-node-oapi.yaml#/components/responses/InternalError' + "503": + $ref: '../../beacon-node-oapi.yaml#/components/responses/CurrentlySyncing' diff --git a/beacon-node-oapi.yaml b/beacon-node-oapi.yaml index a917b743..fd88db98 100644 --- a/beacon-node-oapi.yaml +++ b/beacon-node-oapi.yaml @@ -190,6 +190,8 @@ paths: $ref: "./apis/validator/duties/ptc.yaml" /eth/v3/validator/blocks/{slot}: $ref: "./apis/validator/block.v3.yaml" + /eth/v4/validator/blocks/{slot}: + $ref: "./apis/validator/block.v4.yaml" /eth/v1/validator/attestation_data: $ref: "./apis/validator/attestation_data.yaml" /eth/v1/validator/payload_attestation_data: @@ -513,16 +515,15 @@ components: schema: $ref: '#/components/schemas/ConsensusVersion' Eth-Execution-Payload-Blinded: - description: "DEPRECATED: Not applicable for gloas fork. For pre-gloas forks, this is required in response so client can deserialize returned json or ssz data to the correct object pre-gloas. Post-gloas, there is no concept of blinded blocks." - required: false + description: Required in response so client can deserialize returned json or ssz data to the correct object. + required: true schema: type: boolean Eth-Execution-Payload-Value: description: | - DEPRECATED: Not applicable for gloas fork. - For pre-gloas forks, this is the execution payload value in Wei. Required in response so client can determine relative value - of execution payloads pre-gloas. Post-gloas, the ExecutionPayloadBid defines the value of an execution payload. - required: false + Execution payload value in Wei. Required in response so client can determine relative value + of execution payloads. + required: true schema: $ref: './types/primitive.yaml#/Wei' Eth-Consensus-Block-Value: From 7a3d0e1c91459de0fc0c668b9138069bf01389ea Mon Sep 17 00:00:00 2001 From: shane-moore Date: Fri, 12 Sep 2025 10:02:35 -0700 Subject: [PATCH 10/42] epbs related copy changes --- apis/beacon/blocks/blocks.v2.yaml | 2 +- apis/beacon/execution_payload/bid.yaml | 4 ++-- apis/beacon/execution_payload/envelope.yaml | 3 ++- apis/validator/block.v4.yaml | 2 +- apis/validator/execution_payload_envelope.yaml | 1 + validator-flow.md | 14 +++++++++----- 6 files changed, 16 insertions(+), 10 deletions(-) diff --git a/apis/beacon/blocks/blocks.v2.yaml b/apis/beacon/blocks/blocks.v2.yaml index ef4eb0a0..e96562a1 100644 --- a/apis/beacon/blocks/blocks.v2.yaml +++ b/apis/beacon/blocks/blocks.v2.yaml @@ -11,7 +11,7 @@ post: The beacon node is also expected to integrate the block into the state, but may broadcast it before doing so, so as to aid timely delivery of the block. Should the block fail full validation, a separate success response code (202) is used to indicate that the block was - successfully broadcast but failed integration. After Deneb and before Gloas, this additionally instructs + successfully broadcast but failed integration. For Deneb/Electra/Fulu, this additionally instructs the beacon node to broadcast all given blobs. The broadcast behaviour may be adjusted via the `broadcast_validation` query parameter. parameters: diff --git a/apis/beacon/execution_payload/bid.yaml b/apis/beacon/execution_payload/bid.yaml index 27acab68..5609db69 100644 --- a/apis/beacon/execution_payload/bid.yaml +++ b/apis/beacon/execution_payload/bid.yaml @@ -2,8 +2,8 @@ post: operationId: publishExecutionPayloadBid summary: Publish signed execution payload bid description: | - Instructs the beacon node to broadcast a signed execution payload bid to the beacon network, - to be gossiped for potential inclusion in block building. A success response indicates + Instructs the beacon node to broadcast a signed execution payload bid to the network, + to be gossiped for potential inclusion in block building. A success response (20x) indicates that the bid passed gossip validation and was successfully broadcast onto the network. tags: - Beacon diff --git a/apis/beacon/execution_payload/envelope.yaml b/apis/beacon/execution_payload/envelope.yaml index 6c5c1228..57503623 100644 --- a/apis/beacon/execution_payload/envelope.yaml +++ b/apis/beacon/execution_payload/envelope.yaml @@ -2,11 +2,12 @@ post: operationId: publishExecutionPayloadEnvelope summary: Publish signed execution payload envelope description: | - Instructs the beacon node to broadcast a signed execution payload envelope to the beacon network, + Instructs the beacon node to broadcast a signed execution payload envelope to the network, to be gossiped for payload validation. A success response (20x) indicates that the envelope passed gossip validation and was successfully broadcast onto the network. tags: - Beacon + - ValidatorRequiredApi requestBody: description: "The `SignedExecutionPayloadEnvelope` object to be broadcast." required: true diff --git a/apis/validator/block.v4.yaml b/apis/validator/block.v4.yaml index 3c2dfb9a..38cdbe5d 100644 --- a/apis/validator/block.v4.yaml +++ b/apis/validator/block.v4.yaml @@ -1,7 +1,7 @@ get: tags: - - ValidatorRequiredApi - Validator + - ValidatorRequiredApi operationId: "produceBlockV4" summary: "Produce a new block, without signature." description: | diff --git a/apis/validator/execution_payload_envelope.yaml b/apis/validator/execution_payload_envelope.yaml index d2c86f02..3748e745 100644 --- a/apis/validator/execution_payload_envelope.yaml +++ b/apis/validator/execution_payload_envelope.yaml @@ -7,6 +7,7 @@ get: either as json or as bytes serialized by SSZ. tags: - Validator + - ValidatorRequiredApi parameters: - name: slot in: path diff --git a/validator-flow.md b/validator-flow.md index 86eddc3b..7fbe5245 100644 --- a/validator-flow.md +++ b/validator-flow.md @@ -15,7 +15,9 @@ On start of every epoch, validator should [fetch proposer duties](#/Validator/ge Result is array of objects, each containing proposer pubkey and slot at which he is suppose to propose. If proposing block, then at immediate start of slot: -1. [Ask Beacon Node for BeaconBlock object](#/Validator/produceBlock) +1. Ask Beacon Node for BeaconBlock object: + - Pre-Gloas forks: [produceBlockV3](#/Validator/produceBlockV3) + - Post-Gloas fork: [produceBlockV4](#/Validator/produceBlockV4) 2. Sign block 3. [Submit SignedBeaconBlock](#/ValidatorRequiredApi/publishBlock) (BeaconBlock + signature) @@ -36,13 +38,15 @@ Attesting: been assigned to. If any validators in the committee are aggregators, set `is_aggregator` to `True`, 2. Wait for new BeaconBlock for the assigned slot (either stream updates or poll) - - Max wait: `SECONDS_PER_SLOT / 4` seconds into the assigned slot + - Pre-Gloas forks: Max wait `SECONDS_PER_SLOT / 3` seconds into the assigned slot + - Post-Gloas forks: Max wait `SECONDS_PER_SLOT / 4` seconds into the assigned slot 3. [Fetch AttestationData](#/ValidatorRequiredApi/produceAttestationData) 4. [Submit Attestation](#/ValidatorRequiredApi/submitPoolAttestations) (AttestationData + aggregation bits) - Aggregation bits are `Bitlist` with length of committee (received in AttesterDuty) with bit on position `validator_committee_index` (see AttesterDuty) set to true 5. If aggregator: - - Wait for `SECONDS_PER_SLOT / 2` seconds into the assigned slot + - Pre-Gloas forks: Wait for `SECONDS_PER_SLOT * 2 / 3` seconds into the assigned slot + - Post-Gloas forks: Wait for `SECONDS_PER_SLOT / 2` seconds into the assigned slot - [Fetch aggregated Attestation](#/ValidatorRequiredApi/getAggregatedAttestation) from Beacon Node you've subscribed to your subnet - [Publish SignedAggregateAndProofs](#/ValidatorRequiredApi/publishAggregateAndProofs) @@ -51,7 +55,7 @@ If reorg is detected, ask for new attester duties and proceed from 1.. ### PTC Attesting -On start of every epoch, validator should [fetch PTC duties](#/Validator/getPtcDuties) for epoch + 1. +On start of every epoch beginning with the Gloas fork, validator should [fetch PTC duties](#/Validator/getPtcDuties) for epoch + 1. Result are array of objects with validator index and assigned slot for payload timeliness committee participation. PTC Attesting: @@ -68,7 +72,7 @@ If reorg is detected, ask for new PTC duties and proceed from 1.. ### Builder (Optional) -Validators may optionally act as builders to submit execution payload bids for block inclusion. +Post-Gloas fork, validators may optionally act as builders to submit execution payload bids for block inclusion. This requires registering with builder-specific withdrawal credentials (`BUILDER_WITHDRAWAL_PREFIX`). Building: From be01b6a50e93d41ff81bb6a810aca420a2f05402 Mon Sep 17 00:00:00 2001 From: shane-moore Date: Sat, 13 Sep 2025 10:07:12 -0700 Subject: [PATCH 11/42] add consensus version to bid and envelope post --- apis/beacon/execution_payload/bid.yaml | 7 +++++++ apis/beacon/execution_payload/envelope.yaml | 7 +++++++ 2 files changed, 14 insertions(+) diff --git a/apis/beacon/execution_payload/bid.yaml b/apis/beacon/execution_payload/bid.yaml index 5609db69..8f4f3959 100644 --- a/apis/beacon/execution_payload/bid.yaml +++ b/apis/beacon/execution_payload/bid.yaml @@ -7,6 +7,13 @@ post: that the bid passed gossip validation and was successfully broadcast onto the network. tags: - Beacon + 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 execution payload bid being submitted belongs." requestBody: description: "The `SignedExecutionPayloadBid` object to be broadcast." required: true diff --git a/apis/beacon/execution_payload/envelope.yaml b/apis/beacon/execution_payload/envelope.yaml index 57503623..0837ec48 100644 --- a/apis/beacon/execution_payload/envelope.yaml +++ b/apis/beacon/execution_payload/envelope.yaml @@ -8,6 +8,13 @@ post: tags: - Beacon - ValidatorRequiredApi + 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 execution payload envelope being submitted belongs." requestBody: description: "The `SignedExecutionPayloadEnvelope` object to be broadcast." required: true From 8730379c60cb7f718d3356a10b75ea988e195404 Mon Sep 17 00:00:00 2001 From: shane-moore Date: Sat, 13 Sep 2025 10:39:31 -0700 Subject: [PATCH 12/42] gloas container links updated to use specific commit --- types/gloas/block.yaml | 2 +- types/gloas/execution_payload_bid.yaml | 4 ++-- types/gloas/execution_payload_envelope.yaml | 4 ++-- types/gloas/payload_attestation.yaml | 6 +++--- validator-flow.md | 2 +- 5 files changed, 9 insertions(+), 9 deletions(-) diff --git a/types/gloas/block.yaml b/types/gloas/block.yaml index a849a691..adc6dab0 100644 --- a/types/gloas/block.yaml +++ b/types/gloas/block.yaml @@ -2,7 +2,7 @@ Gloas: 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/master/specs/gloas/beacon-chain.md#beaconblockbody) object from the CL Gloas spec." + description: "The [`BeaconBlockBody`](https://github.com/ethereum/consensus-specs/blob/00d531949b1f30516979b60ddd2a411e7f388299/specs/gloas/beacon-chain.md#beaconblockbody) object from the CL Gloas spec." required: [randao_reveal, eth1_data, graffiti, proposer_slashings, attester_slashings, attestations, deposits, voluntary_exits, sync_aggregate, bls_to_execution_changes] properties: randao_reveal: diff --git a/types/gloas/execution_payload_bid.yaml b/types/gloas/execution_payload_bid.yaml index 771d2d77..14ce0da4 100644 --- a/types/gloas/execution_payload_bid.yaml +++ b/types/gloas/execution_payload_bid.yaml @@ -1,7 +1,7 @@ Gloas: ExecutionPayloadBid: type: object - description: "The [ExecutionPayloadBid](https://github.com/ethereum/consensus-specs/blob/master/specs/gloas/beacon-chain.md#executionpayloadbid) object from the CL gloas spec." + description: "The [`ExecutionPayloadBid`](https://github.com/ethereum/consensus-specs/blob/00d531949b1f30516979b60ddd2a411e7f388299/specs/gloas/beacon-chain.md#executionpayloadbid) object from the CL gloas spec." required: [parent_block_hash, parent_block_root, block_hash, fee_recipient, gas_limit, builder_index, slot, value, blob_kzg_commitments_root] properties: parent_block_hash: @@ -25,7 +25,7 @@ Gloas: SignedExecutionPayloadBid: type: object - description: "The [SignedExecutionPayloadBid](https://github.com/ethereum/consensus-specs/blob/master/specs/gloas/beacon-chain.md#signedexecutionpayloadbid) object from the CL gloas spec." + description: "The [`SignedExecutionPayloadBid`](https://github.com/ethereum/consensus-specs/blob/00d531949b1f30516979b60ddd2a411e7f388299/specs/gloas/beacon-chain.md#signedexecutionpayloadbid) object from the CL gloas spec." required: [message, signature] properties: message: diff --git a/types/gloas/execution_payload_envelope.yaml b/types/gloas/execution_payload_envelope.yaml index de6d3431..e33ed350 100644 --- a/types/gloas/execution_payload_envelope.yaml +++ b/types/gloas/execution_payload_envelope.yaml @@ -1,7 +1,7 @@ Gloas: ExecutionPayloadEnvelope: type: object - description: "The [ExecutionPayloadEnvelope](https://github.com/ethereum/consensus-specs/blob/master/specs/gloas/beacon-chain.md#executionpayloadenvelope) object from the CL gloas spec." + description: "The [`ExecutionPayloadEnvelope`](https://github.com/ethereum/consensus-specs/blob/00d531949b1f30516979b60ddd2a411e7f388299/specs/gloas/beacon-chain.md#executionpayloadenvelope) object from the CL gloas spec." required: [payload, execution_requests, builder_index, beacon_block_root, slot, blob_kzg_commitments, state_root] properties: payload: @@ -34,7 +34,7 @@ Gloas: SignedExecutionPayloadEnvelope: type: object - description: "The [SignedExecutionPayloadEnvelope](https://github.com/ethereum/consensus-specs/blob/master/specs/gloas/beacon-chain.md#signedexecutionpayloadenvelope) object from the CL gloas spec." + description: "The [`SignedExecutionPayloadEnvelope`](https://github.com/ethereum/consensus-specs/blob/00d531949b1f30516979b60ddd2a411e7f388299/specs/gloas/beacon-chain.md#signedexecutionpayloadenvelope) object from the CL gloas spec." required: [message, signature] properties: message: diff --git a/types/gloas/payload_attestation.yaml b/types/gloas/payload_attestation.yaml index 435a5832..93aa9abc 100644 --- a/types/gloas/payload_attestation.yaml +++ b/types/gloas/payload_attestation.yaml @@ -1,7 +1,7 @@ Gloas: PayloadAttestationData: type: object - description: "The [`PayloadAttestationData`](https://github.com/ethereum/consensus-specs/blob/master/specs/gloas/beacon-chain.md#payloadattestationdata) object from the CL Gloas spec." + description: "The [`PayloadAttestationData`](https://github.com/ethereum/consensus-specs/blob/00d531949b1f30516979b60ddd2a411e7f388299/specs/gloas/beacon-chain.md#payloadattestationdata) object from the CL Gloas spec." required: [beacon_block_root, slot, payload_present, blob_data_available] properties: beacon_block_root: @@ -21,7 +21,7 @@ Gloas: PayloadAttestation: type: object - description: "The [PayloadAttestation](https://github.com/ethereum/consensus-specs/blob/master/specs/gloas/beacon-chain.md#payloadattestation) object from the CL gloas spec." + description: "The [`PayloadAttestation`](https://github.com/ethereum/consensus-specs/blob/00d531949b1f30516979b60ddd2a411e7f388299/specs/gloas/beacon-chain.md#payloadattestation) object from the CL gloas spec." required: [aggregation_bits, data, signature] properties: aggregation_bits: @@ -33,7 +33,7 @@ Gloas: PayloadAttestationMessage: type: object - description: "The [`PayloadAttestationMessage`](https://github.com/ethereum/consensus-specs/blob/master/specs/gloas/beacon-chain.md#payloadattestationmessage) object from the CL Gloas spec." + description: "The [`PayloadAttestationMessage`](https://github.com/ethereum/consensus-specs/blob/00d531949b1f30516979b60ddd2a411e7f388299/specs/gloas/beacon-chain.md#payloadattestationmessage) object from the CL Gloas spec." required: [validator_index, data, signature] properties: validator_index: diff --git a/validator-flow.md b/validator-flow.md index 7fbe5245..7dd21f04 100644 --- a/validator-flow.md +++ b/validator-flow.md @@ -78,7 +78,7 @@ This requires registering with builder-specific withdrawal credentials (`BUILDER Building: 1. [Fetch ExecutionPayloadBid](#/Validator/getExecutionPayloadBid) from beacon node - Beacon node obtains payload via `engine_getPayload` call to execution client -2. Cache fields required to form an [ExecutionPayloadEnvelope](https://github.com/ethereum/consensus-specs/blob/master/specs/gloas/beacon-chain.md#executionpayloadenvelope) +2. Cache fields required to form an [ExecutionPayloadEnvelope](https://github.com/ethereum/consensus-specs/blob/00d531949b1f30516979b60ddd2a411e7f388299/specs/gloas/beacon-chain.md#executionpayloadenvelope) 2. Sign ExecutionPayloadBid to create SignedExecutionPayloadBid 3. [Submit SignedExecutionPayloadBid](#/Beacon/publishExecutionPayloadBid) to network for proposer consideration 4. If bid is selected by proposer in their block: From 813c46e4bb360584eda0b999c67d0ad462e1da4f Mon Sep 17 00:00:00 2001 From: shane-moore Date: Mon, 15 Sep 2025 13:18:45 -0700 Subject: [PATCH 13/42] add get bid error message for invalid builder index --- apis/validator/execution_payload_bid.yaml | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/apis/validator/execution_payload_bid.yaml b/apis/validator/execution_payload_bid.yaml index 34901a33..7f8a0db1 100644 --- a/apis/validator/execution_payload_bid.yaml +++ b/apis/validator/execution_payload_bid.yaml @@ -64,5 +64,14 @@ get: message: "Execution payload bid not available for slot and builder" "406": $ref: "../../beacon-node-oapi.yaml#/components/responses/NotAcceptable" + "422": + description: "The builder_index does not correspond to a validator with builder withdrawal credentials (0x03 prefix)" + content: + application/json: + schema: + $ref: "../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage" + example: + code: 422 + message: "Builder index does not correspond to a registered builder validator" "500": $ref: "../../beacon-node-oapi.yaml#/components/responses/InternalError" From 1940d3ffb41581f6b301074401cde45bad43df37 Mon Sep 17 00:00:00 2001 From: shane-moore Date: Wed, 17 Sep 2025 12:52:32 -0700 Subject: [PATCH 14/42] add slot voting time parameters to validator-flow --- validator-flow.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/validator-flow.md b/validator-flow.md index 7dd21f04..d4e0a284 100644 --- a/validator-flow.md +++ b/validator-flow.md @@ -39,14 +39,14 @@ Attesting: set `is_aggregator` to `True`, 2. Wait for new BeaconBlock for the assigned slot (either stream updates or poll) - Pre-Gloas forks: Max wait `SECONDS_PER_SLOT / 3` seconds into the assigned slot - - Post-Gloas forks: Max wait `SECONDS_PER_SLOT / 4` seconds into the assigned slot + - Post-Gloas forks: Max wait [ATTESTATION_DUE_BPS_GLOAS](https://github.com/ethereum/consensus-specs/blob/00d531949b1f30516979b60ddd2a411e7f388299/specs/gloas/validator.md#time-parameters) seconds into the assigned slot 3. [Fetch AttestationData](#/ValidatorRequiredApi/produceAttestationData) 4. [Submit Attestation](#/ValidatorRequiredApi/submitPoolAttestations) (AttestationData + aggregation bits) - Aggregation bits are `Bitlist` with length of committee (received in AttesterDuty) with bit on position `validator_committee_index` (see AttesterDuty) set to true 5. If aggregator: - Pre-Gloas forks: Wait for `SECONDS_PER_SLOT * 2 / 3` seconds into the assigned slot - - Post-Gloas forks: Wait for `SECONDS_PER_SLOT / 2` seconds into the assigned slot + - Post-Gloas forks: Wait for [AGGREGATE_DUE_BPS_GLOAS](https://github.com/ethereum/consensus-specs/blob/00d531949b1f30516979b60ddd2a411e7f388299/specs/gloas/validator.md#time-parameters) seconds into the assigned slot - [Fetch aggregated Attestation](#/ValidatorRequiredApi/getAggregatedAttestation) from Beacon Node you've subscribed to your subnet - [Publish SignedAggregateAndProofs](#/ValidatorRequiredApi/publishAggregateAndProofs) @@ -64,7 +64,7 @@ PTC Attesting: 2. [Fetch PayloadAttestationData](#/ValidatorRequiredApi/producePayloadAttestationData) for the assigned slot 3. Sign PayloadAttestationData to create PayloadAttestationMessage 4. [Submit PayloadAttestationMessage](#/ValidatorRequiredApi/submitPayloadAttestationMessage) - - Must be submitted by `3/4` of slot duration (`PAYLOAD_ATTESTATION_DUE_BPS` = 75% of slot) + - Must be submitted by [PAYLOAD_ATTESTATION_DUE_BPS](https://github.com/ethereum/consensus-specs/blob/00d531949b1f30516979b60ddd2a411e7f388299/specs/gloas/validator.md#time-parameters) of slot duration - Attestation indicates whether execution payload envelope has been seen for the block and if blobs were received Monitor chain block reorganization events (TBD) as they could change PTC assignments. @@ -84,7 +84,7 @@ Building: 4. If bid is selected by proposer in their block: - [Fetch ExecutionPayloadEnvelope](#/Validator/getExecutionPayloadEnvelope) from beacon node - Sign envelope and [submit SignedExecutionPayloadEnvelope](#/Beacon/publishExecutionPayloadEnvelope) - - Must submit early enough for PTC attestation by `3/4` of slot duration + - Must submit early enough for PTC attestation by [PAYLOAD_ATTESTATION_DUE_BPS](https://github.com/ethereum/consensus-specs/blob/00d531949b1f30516979b60ddd2a411e7f388299/specs/gloas/validator.md#time-parameters) of slot duration Monitor for block proposals containing your bid to trigger envelope release. From 994c2b771ead2ecec46b20363ed036a153fe202d Mon Sep 17 00:00:00 2001 From: shane-moore Date: Wed, 17 Sep 2025 13:48:56 -0700 Subject: [PATCH 15/42] add eth-consensus-version for payload attestations --- apis/beacon/pool/payload_attestations.yaml | 10 ++++++++++ apis/validator/payload_attestation_data.yaml | 9 ++++++++- 2 files changed, 18 insertions(+), 1 deletion(-) diff --git a/apis/beacon/pool/payload_attestations.yaml b/apis/beacon/pool/payload_attestations.yaml index 3bcc47cb..b8b4f5a2 100644 --- a/apis/beacon/pool/payload_attestations.yaml +++ b/apis/beacon/pool/payload_attestations.yaml @@ -13,6 +13,9 @@ get: responses: "200": description: Successful response + headers: + Eth-Consensus-Version: + $ref: '../../../beacon-node-oapi.yaml#/components/headers/Eth-Consensus-Version' content: application/json: schema: @@ -51,6 +54,13 @@ post: A success response indicates that the payload attestation message passed validation and was successfully stored and broadcast. + 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 payload attestation message being submitted belongs." tags: - Beacon - ValidatorRequiredApi diff --git a/apis/validator/payload_attestation_data.yaml b/apis/validator/payload_attestation_data.yaml index e13973b6..693a6798 100644 --- a/apis/validator/payload_attestation_data.yaml +++ b/apis/validator/payload_attestation_data.yaml @@ -21,13 +21,20 @@ get: responses: "200": description: "Success response" + headers: + Eth-Consensus-Version: + $ref: "../../beacon-node-oapi.yaml#/components/headers/Eth-Consensus-Version" content: application/json: schema: title: ProducePayloadAttestationDataResponse type: object - required: [data] + required: [version, data] properties: + version: + type: string + enum: [gloas] + example: "gloas" data: $ref: "../../beacon-node-oapi.yaml#/components/schemas/Gloas.PayloadAttestationData" application/octet-stream: From 6def5f7e3fb6a5fc26a4e23f36c15570426e4e20 Mon Sep 17 00:00:00 2001 From: shane-moore Date: Thu, 18 Sep 2025 08:55:19 -0700 Subject: [PATCH 16/42] update payload attestation get to have slot in path --- apis/validator/payload_attestation_data.yaml | 2 +- beacon-node-oapi.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/apis/validator/payload_attestation_data.yaml b/apis/validator/payload_attestation_data.yaml index 693a6798..f777b32b 100644 --- a/apis/validator/payload_attestation_data.yaml +++ b/apis/validator/payload_attestation_data.yaml @@ -13,7 +13,7 @@ get: A 503 error must be returned if the beacon node is currently syncing. parameters: - name: slot - in: query + in: path required: true description: "The slot for which payload attestation data should be created." schema: diff --git a/beacon-node-oapi.yaml b/beacon-node-oapi.yaml index fd88db98..61d51d80 100644 --- a/beacon-node-oapi.yaml +++ b/beacon-node-oapi.yaml @@ -194,7 +194,7 @@ paths: $ref: "./apis/validator/block.v4.yaml" /eth/v1/validator/attestation_data: $ref: "./apis/validator/attestation_data.yaml" - /eth/v1/validator/payload_attestation_data: + /eth/v1/validator/payload_attestation_data/{slot}: $ref: "./apis/validator/payload_attestation_data.yaml" /eth/v2/validator/aggregate_attestation: $ref: "./apis/validator/aggregate_attestation.v2.yaml" From 17869db15131d68914cdbaaf39eed3be4c9a4776 Mon Sep 17 00:00:00 2001 From: shane-moore Date: Fri, 19 Sep 2025 18:05:37 -0700 Subject: [PATCH 17/42] payload attestation post should support an array in the request --- apis/beacon/pool/payload_attestations.yaml | 24 +++++++++++----------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/apis/beacon/pool/payload_attestations.yaml b/apis/beacon/pool/payload_attestations.yaml index b8b4f5a2..53c4ba92 100644 --- a/apis/beacon/pool/payload_attestations.yaml +++ b/apis/beacon/pool/payload_attestations.yaml @@ -47,13 +47,15 @@ post: operationId: submitPayloadAttestationMessage summary: Submit payload attestation message description: | - Submits a payload attestation message to the beacon node. + Submits payload attestation messages to the beacon node. - The beacon node will validate the payload attestation message according to the gossip validation rules + The beacon node will validate each payload attestation message according to the gossip validation rules and, if valid, store it in the pool and broadcast it globally to the network. A success response indicates that the payload attestation message passed validation and was successfully stored and broadcast. + + If one or more payload attestation messages fail validation, the node MUST return a 400 error with details of which messages have failed, and why. parameters: - in: header schema: @@ -65,28 +67,26 @@ post: - Beacon - ValidatorRequiredApi requestBody: - description: "The PayloadAttestationMessage object to be submitted." + description: "Array of PayloadAttestationMessage objects to be submitted." required: true content: application/json: schema: - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Gloas.PayloadAttestationMessage" + type: array + items: + $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Gloas.PayloadAttestationMessage" application/octet-stream: schema: - description: "SSZ serialized PayloadAttestationMessage bytes. Use Content-Type header to indicate that SSZ data is contained in the request body." + description: "SSZ serialized array of PayloadAttestationMessage bytes. Use Content-Type header to indicate that SSZ data is contained in the request body." responses: "200": - description: "The payload attestation message was stored in the pool and has been broadcast." - content: - text/plain: - schema: - type: string + description: "Payload attestation messages are stored in pool and broadcasted to the network" "400": - description: "The PayloadAttestationMessage object is invalid or failed gossip validation" + description: "Errors with one or more payload attestation messages" content: application/json: schema: - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage" + $ref: "../../../beacon-node-oapi.yaml#/components/schemas/IndexedErrorMessage" "415": $ref: "../../../beacon-node-oapi.yaml#/components/responses/UnsupportedMediaType" "500": From 5b395c39866d173b301e7873ff8edcde9c97a00e Mon Sep 17 00:00:00 2001 From: shane-moore Date: Tue, 4 Nov 2025 09:54:58 -0800 Subject: [PATCH 18/42] updates per nico review --- apis/beacon/execution_payload/bid.yaml | 8 +---- apis/beacon/execution_payload/envelope.yaml | 8 +---- apis/beacon/pool/payload_attestations.yaml | 6 ++-- apis/eventstream/index.yaml | 6 ++++ apis/validator/block.v4.yaml | 4 +-- apis/validator/execution_payload_bid.yaml | 31 +++++++--------- .../validator/execution_payload_envelope.yaml | 10 ++---- apis/validator/payload_attestation_data.yaml | 2 +- types/gloas/block.yaml | 35 +++++++------------ types/gloas/execution_payload_envelope.yaml | 25 ++++++------- types/gloas/payload_attestation.yaml | 20 +++++------ validator-flow.md | 14 +++++--- 12 files changed, 69 insertions(+), 100 deletions(-) diff --git a/apis/beacon/execution_payload/bid.yaml b/apis/beacon/execution_payload/bid.yaml index 8f4f3959..e3608201 100644 --- a/apis/beacon/execution_payload/bid.yaml +++ b/apis/beacon/execution_payload/bid.yaml @@ -23,14 +23,10 @@ post: $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" + description: "SSZ serialized `SignedExecutionPayloadBid` bytes. Use Content-Type header to specify this format" responses: "200": description: "The bid was validated successfully and has been broadcast." - content: - text/plain: - schema: - type: string "400": description: "The SignedExecutionPayloadBid object is invalid or failed gossip validation" content: @@ -40,8 +36,6 @@ post: example: code: 400 message: "Invalid signed execution payload bid" - "406": - $ref: "../../../beacon-node-oapi.yaml#/components/responses/NotAcceptable" "415": $ref: "../../../beacon-node-oapi.yaml#/components/responses/UnsupportedMediaType" "500": diff --git a/apis/beacon/execution_payload/envelope.yaml b/apis/beacon/execution_payload/envelope.yaml index 0837ec48..0b3ac276 100644 --- a/apis/beacon/execution_payload/envelope.yaml +++ b/apis/beacon/execution_payload/envelope.yaml @@ -24,14 +24,10 @@ post: $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Gloas.SignedExecutionPayloadEnvelope" application/octet-stream: schema: - description: "SSZ serialized SignedExecutionPayloadEnvelope bytes. Use Content-Type header to specify this format" + description: "SSZ serialized `SignedExecutionPayloadEnvelope` bytes. Use Content-Type header to specify this format" responses: "200": description: "The envelope was validated successfully and has been broadcast." - content: - text/plain: - schema: - type: string "400": description: "The SignedExecutionPayloadEnvelope object is invalid or failed gossip validation" content: @@ -41,8 +37,6 @@ post: example: code: 400 message: "Invalid signed execution payload envelope" - "406": - $ref: "../../../beacon-node-oapi.yaml#/components/responses/NotAcceptable" "415": $ref: "../../../beacon-node-oapi.yaml#/components/responses/UnsupportedMediaType" "500": diff --git a/apis/beacon/pool/payload_attestations.yaml b/apis/beacon/pool/payload_attestations.yaml index 53c4ba92..8a3cdd68 100644 --- a/apis/beacon/pool/payload_attestations.yaml +++ b/apis/beacon/pool/payload_attestations.yaml @@ -44,8 +44,8 @@ get: $ref: "../../../beacon-node-oapi.yaml#/components/responses/InternalError" post: - operationId: submitPayloadAttestationMessage - summary: Submit payload attestation message + operationId: submitPayloadAttestationMessages + summary: Submit payload attestation messages description: | Submits payload attestation messages to the beacon node. @@ -77,7 +77,7 @@ post: $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Gloas.PayloadAttestationMessage" application/octet-stream: schema: - description: "SSZ serialized array of PayloadAttestationMessage bytes. Use Content-Type header to indicate that SSZ data is contained in the request body." + description: "SSZ serialized `List[PayloadAttestationMessage, PTC_SIZE]` bytes. Use Content-Type header to indicate that SSZ data is contained in the request body." responses: "200": description: "Payload attestation messages are stored in pool and broadcasted to the network" diff --git a/apis/eventstream/index.yaml b/apis/eventstream/index.yaml index 3ed6dc86..0acf2df5 100644 --- a/apis/eventstream/index.yaml +++ b/apis/eventstream/index.yaml @@ -39,6 +39,7 @@ get: - payload_attributes - blob_sidecar - data_column_sidecar + - execution_payload_available responses: "200": description: Opened SSE stream. @@ -158,6 +159,11 @@ get: value: | event: data_column_sidecar data: {"block_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", "index": "1", "slot": "1", "kzg_commitments": ["0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505"]} + execution_payload_available: + description: The node has verified that the execution payload and blobs for a block are available and ready for payload attestation + value: | + event: execution_payload_available + data: {"slot": "10", "block_root": "0x9a2fefd2fdb57f74993c7780ea5b9030d2897b615b89f808011ca5aebed54eaf"} "400": description: "The topics supplied could not be parsed" content: diff --git a/apis/validator/block.v4.yaml b/apis/validator/block.v4.yaml index 38cdbe5d..f53f4241 100644 --- a/apis/validator/block.v4.yaml +++ b/apis/validator/block.v4.yaml @@ -77,7 +77,7 @@ get: schema: title: "ProduceBlockV4Response" type: object - required: [version, data, consensus_block_value] + required: [version, consensus_block_value, data] properties: version: type: string @@ -91,7 +91,7 @@ get: $ref: "../../beacon-node-oapi.yaml#/components/schemas/Gloas.BeaconBlock" 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`." + description: "SSZ serialized `BeaconBlock` bytes. Use Accept header to choose this response type, version string is sent in header `Eth-Consensus-Version`." "400": description: "Invalid block production request" content: diff --git a/apis/validator/execution_payload_bid.yaml b/apis/validator/execution_payload_bid.yaml index 7f8a0db1..9f129481 100644 --- a/apis/validator/execution_payload_bid.yaml +++ b/apis/validator/execution_payload_bid.yaml @@ -29,30 +29,32 @@ get: schema: title: GetExecutionPayloadBidResponse type: object - required: [version, execution_optimistic, finalized, data] + required: [version, data] properties: version: type: string enum: [gloas] example: "gloas" - execution_optimistic: - $ref: "../../beacon-node-oapi.yaml#/components/schemas/ExecutionOptimistic" - finalized: - $ref: "../../beacon-node-oapi.yaml#/components/schemas/Finalized" data: $ref: "../../beacon-node-oapi.yaml#/components/schemas/Gloas.ExecutionPayloadBid" application/octet-stream: schema: - description: "SSZ serialized execution payload bid bytes. Use Accept header to choose this response type" + description: "SSZ serialized `ExecutionPayloadBid` bytes. Use Accept header to choose this response type" "400": - description: "The slot supplied could not be parsed or is invalid" + description: "Invalid request - the slot or builder_index is invalid" content: application/json: schema: $ref: "../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage" - example: - code: 400 - message: "Invalid slot: must be current slot or next slot" + examples: + InvalidSlot: + value: + code: 400 + message: "Invalid slot: must be current slot or next slot" + InvalidBuilderIndex: + value: + code: 400 + message: "Builder index does not correspond to a registered builder validator" "404": description: "Execution payload bid not available for the requested slot and builder" content: @@ -64,14 +66,5 @@ get: message: "Execution payload bid not available for slot and builder" "406": $ref: "../../beacon-node-oapi.yaml#/components/responses/NotAcceptable" - "422": - description: "The builder_index does not correspond to a validator with builder withdrawal credentials (0x03 prefix)" - content: - application/json: - schema: - $ref: "../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage" - example: - code: 422 - message: "Builder index does not correspond to a registered builder validator" "500": $ref: "../../beacon-node-oapi.yaml#/components/responses/InternalError" diff --git a/apis/validator/execution_payload_envelope.yaml b/apis/validator/execution_payload_envelope.yaml index 3748e745..3d04b672 100644 --- a/apis/validator/execution_payload_envelope.yaml +++ b/apis/validator/execution_payload_envelope.yaml @@ -18,7 +18,7 @@ get: - name: builder_index in: path required: true - description: "Index of the builder from which the execution payload envelope is requested." + description: "Validator index of the builder from which the execution payload envelope is requested. For self-building, it will be the proposer's validator index." schema: $ref: "../../beacon-node-oapi.yaml#/components/schemas/Uint64" responses: @@ -32,21 +32,17 @@ get: schema: title: GetExecutionPayloadEnvelopeResponse type: object - required: [version, execution_optimistic, finalized, data] + required: [version, data] properties: version: type: string enum: [gloas] example: "gloas" - execution_optimistic: - $ref: "../../beacon-node-oapi.yaml#/components/schemas/ExecutionOptimistic" - finalized: - $ref: "../../beacon-node-oapi.yaml#/components/schemas/Finalized" data: $ref: "../../beacon-node-oapi.yaml#/components/schemas/Gloas.ExecutionPayloadEnvelope" application/octet-stream: schema: - description: "SSZ serialized execution payload envelope bytes. Use Accept header to choose this response type" + description: "SSZ serialized `ExecutionPayloadEnvelope` bytes. Use Accept header to choose this response type" "400": description: "Invalid execution payload envelope request" content: diff --git a/apis/validator/payload_attestation_data.yaml b/apis/validator/payload_attestation_data.yaml index f777b32b..4fb35304 100644 --- a/apis/validator/payload_attestation_data.yaml +++ b/apis/validator/payload_attestation_data.yaml @@ -39,7 +39,7 @@ get: $ref: "../../beacon-node-oapi.yaml#/components/schemas/Gloas.PayloadAttestationData" application/octet-stream: schema: - description: "SSZ serialized PayloadAttestationData bytes. Use Accept header to choose this response type" + description: "SSZ serialized `PayloadAttestationData` bytes. Use Accept header to choose this response type" "400": $ref: "../../beacon-node-oapi.yaml#/components/responses/InvalidRequest" "406": diff --git a/types/gloas/block.yaml b/types/gloas/block.yaml index adc6dab0..6c4bea95 100644 --- a/types/gloas/block.yaml +++ b/types/gloas/block.yaml @@ -1,14 +1,12 @@ Gloas: - BeaconBlockBodyCommon: - # An abstract object to collect the common fields between the BeaconBlockBody and the BlindedBeaconBlockBody objects + BeaconBlockBody: type: object description: "The [`BeaconBlockBody`](https://github.com/ethereum/consensus-specs/blob/00d531949b1f30516979b60ddd2a411e7f388299/specs/gloas/beacon-chain.md#beaconblockbody) object from the CL Gloas spec." - required: [randao_reveal, eth1_data, graffiti, proposer_slashings, attester_slashings, attestations, deposits, voluntary_exits, sync_aggregate, bls_to_execution_changes] + required: [randao_reveal, eth1_data, graffiti, proposer_slashings, attester_slashings, attestations, deposits, voluntary_exits, sync_aggregate, bls_to_execution_changes, signed_execution_payload_bid, payload_attestations] properties: randao_reveal: - allOf: - - $ref: "../primitive.yaml#/Signature" - - description: "The RANDAO reveal value provided by the validator." + $ref: "../primitive.yaml#/Signature" + description: "The RANDAO reveal value provided by the validator." eth1_data: $ref: "../phase0/eth1.yaml#/Phase0/Eth1Data" graffiti: @@ -39,22 +37,15 @@ Gloas: type: array items: $ref: "../capella/bls_to_execution_change.yaml#/Capella/SignedBLSToExecutionChange" - - BeaconBlockBody: - allOf: - - $ref: "#/Gloas/BeaconBlockBodyCommon" - - type: object - required: [signed_execution_payload_bid, payload_attestations] - properties: - signed_execution_payload_bid: - $ref: "./execution_payload_bid.yaml#/Gloas/SignedExecutionPayloadBid" - payload_attestations: - type: array - description: "Array of payload attestations from gloas." - items: - $ref: "./payload_attestation.yaml#/Gloas/PayloadAttestation" - minItems: 0 - maxItems: 4 + signed_execution_payload_bid: + $ref: "./execution_payload_bid.yaml#/Gloas/SignedExecutionPayloadBid" + payload_attestations: + type: array + description: "Array of payload attestations from gloas." + items: + $ref: "./payload_attestation.yaml#/Gloas/PayloadAttestation" + minItems: 0 + maxItems: 4 BeaconBlock: description: "The [`BeaconBlock`](https://github.com/ethereum/consensus-specs/blob/v1.5.0/specs/phase0/beacon-chain.md#beaconblock) object from the CL Gloas spec." diff --git a/types/gloas/execution_payload_envelope.yaml b/types/gloas/execution_payload_envelope.yaml index e33ed350..7baf80f0 100644 --- a/types/gloas/execution_payload_envelope.yaml +++ b/types/gloas/execution_payload_envelope.yaml @@ -9,17 +9,14 @@ Gloas: execution_requests: $ref: "../electra/execution_requests.yaml#/Electra/ExecutionRequests" builder_index: - allOf: - - $ref: "../primitive.yaml#/Uint64" - - description: "Index of the builder that created this execution payload" + $ref: "../primitive.yaml#/Uint64" + description: "Index of the builder that created this execution payload" beacon_block_root: - allOf: - - $ref: "../primitive.yaml#/Root" - - description: "Root of the beacon block for this payload" + $ref: "../primitive.yaml#/Root" + description: "Root of the beacon block for this payload" slot: - allOf: - - $ref: "../primitive.yaml#/Uint64" - - description: "Slot number for this execution payload" + $ref: "../primitive.yaml#/Uint64" + description: "Slot number for this execution payload" blob_kzg_commitments: type: array items: @@ -28,9 +25,8 @@ Gloas: maxItems: 4096 description: "KZG commitments for the blobs included in this execution payload" state_root: - allOf: - - $ref: "../primitive.yaml#/Root" - - description: "Beacon state root after executing this payload" + $ref: "../primitive.yaml#/Root" + description: "Beacon state root after executing this payload" SignedExecutionPayloadEnvelope: type: object @@ -40,6 +36,5 @@ Gloas: message: $ref: "#/Gloas/ExecutionPayloadEnvelope" signature: - allOf: - - $ref: "../primitive.yaml#/Signature" - - description: "BLS signature of the execution payload envelope" + $ref: "../primitive.yaml#/Signature" + description: "BLS signature of the execution payload envelope" diff --git a/types/gloas/payload_attestation.yaml b/types/gloas/payload_attestation.yaml index 93aa9abc..82eb5b7d 100644 --- a/types/gloas/payload_attestation.yaml +++ b/types/gloas/payload_attestation.yaml @@ -5,13 +5,11 @@ Gloas: required: [beacon_block_root, slot, payload_present, blob_data_available] properties: beacon_block_root: - allOf: - - $ref: "../primitive.yaml#/Root" - - description: "Hash tree root of the beacon block associated with this ptc attestation" + $ref: "../primitive.yaml#/Root" + description: "Hash tree root of the beacon block associated with this ptc attestation" slot: - allOf: - - $ref: "../primitive.yaml#/Uint64" - - description: "The slot for which the payload attestation is being made" + $ref: "../primitive.yaml#/Uint64" + description: "The slot for which the payload attestation is being made" payload_present: type: boolean description: "True if a SignedExecutionPayloadEnvelope has been seen referencing this block" @@ -37,12 +35,10 @@ Gloas: required: [validator_index, data, signature] properties: validator_index: - allOf: - - $ref: "../primitive.yaml#/Uint64" - - description: "Index of the validator submitting the payload attestation" + $ref: "../primitive.yaml#/Uint64" + description: "Index of the validator submitting the payload attestation" data: $ref: "#/Gloas/PayloadAttestationData" signature: - allOf: - - $ref: "../primitive.yaml#/Signature" - - description: "BLS signature of the payload attestation data" + $ref: "../primitive.yaml#/Signature" + description: "BLS signature of the payload attestation data" diff --git a/validator-flow.md b/validator-flow.md index d4e0a284..8d47db17 100644 --- a/validator-flow.md +++ b/validator-flow.md @@ -20,10 +20,15 @@ If proposing block, then at immediate start of slot: - Post-Gloas fork: [produceBlockV4](#/Validator/produceBlockV4) 2. Sign block 3. [Submit SignedBeaconBlock](#/ValidatorRequiredApi/publishBlock) (BeaconBlock + signature) +4. Post-Gloas, if self-building (proposer's own bid included in block): + - [Fetch ExecutionPayloadEnvelope](#/Validator/getExecutionPayloadEnvelope) from beacon node + - Sign envelope and [submit SignedExecutionPayloadEnvelope](#/Beacon/publishExecutionPayloadEnvelope) + - Must submit early enough for PTC attestation by [PAYLOAD_ATTESTATION_DUE_BPS](https://github.com/ethereum/consensus-specs/blob/00d531949b1f30516979b60ddd2a411e7f388299/specs/gloas/validator.md#time-parameters) of slot duration Monitor chain block reorganization events (TBD) as they could change block proposers. If reorg is detected, ask for new proposer duties and proceed from 1. + ### Attestation On start of every epoch, validator should ask for attester duties for epoch + 1. @@ -59,12 +64,11 @@ On start of every epoch beginning with the Gloas fork, validator should [fetch P Result are array of objects with validator index and assigned slot for payload timeliness committee participation. PTC Attesting: -1. Wait for new BeaconBlock for the assigned slot - - Max wait: `SECONDS_PER_SLOT / 4` seconds into the assigned slot +1. Wait for execution payload and blobs to become available for the assigned slot (either stream updates or poll) + - Max wait [PAYLOAD_ATTESTATION_DUE_BPS](https://github.com/ethereum/consensus-specs/blob/00d531949b1f30516979b60ddd2a411e7f388299/specs/gloas/validator.md#time-parameters) seconds into the assigned slot 2. [Fetch PayloadAttestationData](#/ValidatorRequiredApi/producePayloadAttestationData) for the assigned slot 3. Sign PayloadAttestationData to create PayloadAttestationMessage -4. [Submit PayloadAttestationMessage](#/ValidatorRequiredApi/submitPayloadAttestationMessage) - - Must be submitted by [PAYLOAD_ATTESTATION_DUE_BPS](https://github.com/ethereum/consensus-specs/blob/00d531949b1f30516979b60ddd2a411e7f388299/specs/gloas/validator.md#time-parameters) of slot duration +4. [Submit PayloadAttestationMessages](#/ValidatorRequiredApi/submitPayloadAttestationMessages) - Attestation indicates whether execution payload envelope has been seen for the block and if blobs were received Monitor chain block reorganization events (TBD) as they could change PTC assignments. @@ -76,7 +80,7 @@ Post-Gloas fork, validators may optionally act as builders to submit execution p This requires registering with builder-specific withdrawal credentials (`BUILDER_WITHDRAWAL_PREFIX`). Building: -1. [Fetch ExecutionPayloadBid](#/Validator/getExecutionPayloadBid) from beacon node +1. [Fetch ExecutionPayloadBid](#/Validator/getExecutionPayloadBid) from beacon node for the current or next slot's proposer to include. - Beacon node obtains payload via `engine_getPayload` call to execution client 2. Cache fields required to form an [ExecutionPayloadEnvelope](https://github.com/ethereum/consensus-specs/blob/00d531949b1f30516979b60ddd2a411e7f388299/specs/gloas/beacon-chain.md#executionpayloadenvelope) 2. Sign ExecutionPayloadBid to create SignedExecutionPayloadBid From 6dea1bb3bd534e23a7b47c9449c9a2371aed670a Mon Sep 17 00:00:00 2001 From: shane-moore Date: Tue, 4 Nov 2025 11:28:35 -0800 Subject: [PATCH 19/42] get execution payload envelope by block id --- CHANGES.md | 1 + apis/beacon/blocks/block.v2.yaml | 5 +- .../execution_payload/envelope_get.yaml | 58 +++++++++++++++++++ .../{envelope.yaml => envelope_post.yaml} | 0 beacon-node-oapi.yaml | 4 +- 5 files changed, 65 insertions(+), 3 deletions(-) create mode 100644 apis/beacon/execution_payload/envelope_get.yaml rename apis/beacon/execution_payload/{envelope.yaml => envelope_post.yaml} (100%) diff --git a/CHANGES.md b/CHANGES.md index 0f74dad5..fbd7e46d 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -13,6 +13,7 @@ There are likely to be descriptions etc outside of the list below, but new query | [#552](https://github.com/ethereum/beacon-APIs/pull/552) `GET /eth/v1/validator/payload_attestation_data` added | | | | | | | [#552](https://github.com/ethereum/beacon-APIs/pull/552) `POST /eth/v1/validator/duties/ptc/{epoch}` added | | | | | | | [#552](https://github.com/ethereum/beacon-APIs/pull/552) `POST /eth/v1/beacon/execution_payload_bid` added | | | | | | +| [#552](https://github.com/ethereum/beacon-APIs/pull/552) `GET /eth/v1/beacon/execution_payload_envelope/{block_id}` added | | | | | | | [#552](https://github.com/ethereum/beacon-APIs/pull/552) `POST /eth/v1/beacon/execution_payload_envelope` added | | | | | | | [#552](https://github.com/ethereum/beacon-APIs/pull/552) `POST /eth/v1/beacon/pool/payload_attestations` added | | | | | | | [#552](https://github.com/ethereum/beacon-APIs/pull/552) `GET /eth/v4/validator/blocks/{slot}` added | | | | | | diff --git a/apis/beacon/blocks/block.v2.yaml b/apis/beacon/blocks/block.v2.yaml index 569276a0..b0c6a851 100644 --- a/apis/beacon/blocks/block.v2.yaml +++ b/apis/beacon/blocks/block.v2.yaml @@ -26,14 +26,15 @@ get: properties: version: type: string - enum: [phase0, altair, bellatrix, capella, deneb, electra, fulu] - example: "fulu" + enum: [phase0, altair, bellatrix, capella, deneb, electra, fulu, gloas] + example: "gloas" execution_optimistic: $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ExecutionOptimistic" finalized: $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Finalized" data: anyOf: + - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Gloas.SignedBeaconBlock" - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Electra.SignedBeaconBlock" - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Deneb.SignedBeaconBlock" - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Capella.SignedBeaconBlock" diff --git a/apis/beacon/execution_payload/envelope_get.yaml b/apis/beacon/execution_payload/envelope_get.yaml new file mode 100644 index 00000000..124567dd --- /dev/null +++ b/apis/beacon/execution_payload/envelope_get.yaml @@ -0,0 +1,58 @@ +get: + operationId: getExecutionPayloadEnvelopeByBlockId + summary: Get execution payload envelope + description: | + Retrieves execution payload envelope for a given block id. + Depending on `Accept` header it can be returned either as json or as bytes serialized by SSZ. + tags: + - Beacon + parameters: + - $ref: '../../../beacon-node-oapi.yaml#/components/parameters/BlockId' + responses: + "200": + description: "Successful response" + headers: + Eth-Consensus-Version: + $ref: '../../../beacon-node-oapi.yaml#/components/headers/Eth-Consensus-Version' + content: + application/json: + schema: + title: GetExecutionPayloadEnvelopeResponse + type: object + required: [version, execution_optimistic, finalized, data] + properties: + version: + type: string + enum: [gloas] + example: "gloas" + execution_optimistic: + $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ExecutionOptimistic" + finalized: + $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Finalized" + data: + $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Gloas.SignedExecutionPayloadEnvelope" + application/octet-stream: + schema: + description: "SSZ serialized execution payload envelope bytes. Use Accept header to choose this response type" + "400": + description: "The block ID supplied could not be parsed" + content: + application/json: + schema: + $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage" + example: + code: 400 + message: "Invalid block ID: current" + "404": + description: "Execution payload envelope not found" + content: + application/json: + schema: + $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage" + example: + code: 404 + message: "Execution payload envelope 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/execution_payload/envelope.yaml b/apis/beacon/execution_payload/envelope_post.yaml similarity index 100% rename from apis/beacon/execution_payload/envelope.yaml rename to apis/beacon/execution_payload/envelope_post.yaml diff --git a/beacon-node-oapi.yaml b/beacon-node-oapi.yaml index 61d51d80..dc612d42 100644 --- a/beacon-node-oapi.yaml +++ b/beacon-node-oapi.yaml @@ -107,7 +107,9 @@ paths: /eth/v1/beacon/execution_payload_bid: $ref: "./apis/beacon/execution_payload/bid.yaml" /eth/v1/beacon/execution_payload_envelope: - $ref: "./apis/beacon/execution_payload/envelope.yaml" + $ref: "./apis/beacon/execution_payload/envelope_post.yaml" + /eth/v1/beacon/execution_payload_envelope/{block_id}: + $ref: "./apis/beacon/execution_payload/envelope_get.yaml" /eth/v2/beacon/blocks/{block_id}: $ref: "./apis/beacon/blocks/block.v2.yaml" /eth/v1/beacon/blocks/{block_id}/root: From 1e114530e3cedf14874c467593b472210f07b3e8 Mon Sep 17 00:00:00 2001 From: shane-moore Date: Wed, 5 Nov 2025 05:16:32 -0800 Subject: [PATCH 20/42] updates per nico review --- apis/beacon/execution_payload/envelope_get.yaml | 6 +++--- apis/beacon/pool/payload_attestations.yaml | 2 +- apis/validator/execution_payload_envelope.yaml | 2 +- types/gloas/execution_payload_bid.yaml | 4 ++-- types/gloas/execution_payload_envelope.yaml | 4 ++-- types/gloas/payload_attestation.yaml | 2 +- wordlist.txt | 4 ++++ 7 files changed, 14 insertions(+), 10 deletions(-) diff --git a/apis/beacon/execution_payload/envelope_get.yaml b/apis/beacon/execution_payload/envelope_get.yaml index 124567dd..574827e4 100644 --- a/apis/beacon/execution_payload/envelope_get.yaml +++ b/apis/beacon/execution_payload/envelope_get.yaml @@ -1,8 +1,8 @@ get: - operationId: getExecutionPayloadEnvelopeByBlockId - summary: Get execution payload envelope + operationId: getSignedExecutionPayloadEnvelope + summary: Get signed execution payload envelope description: | - Retrieves execution payload envelope for a given block id. + Retrieves signed execution payload envelope for a given block id. Depending on `Accept` header it can be returned either as json or as bytes serialized by SSZ. tags: - Beacon diff --git a/apis/beacon/pool/payload_attestations.yaml b/apis/beacon/pool/payload_attestations.yaml index 8a3cdd68..4a2dfced 100644 --- a/apis/beacon/pool/payload_attestations.yaml +++ b/apis/beacon/pool/payload_attestations.yaml @@ -30,7 +30,7 @@ get: data: type: array items: - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Gloas.PayloadAttestationMessage" + $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Gloas.PayloadAttestation" "400": description: "The slot could not be parsed" content: diff --git a/apis/validator/execution_payload_envelope.yaml b/apis/validator/execution_payload_envelope.yaml index 3d04b672..d6463b1c 100644 --- a/apis/validator/execution_payload_envelope.yaml +++ b/apis/validator/execution_payload_envelope.yaml @@ -2,7 +2,7 @@ get: operationId: getExecutionPayloadEnvelope summary: Get execution payload envelope description: | - Retrieves execution payload envelope for a given slot and builder. The envelope contains the full + Retrieves execution payload envelope for a given slot and builder, which can then be signed by a validator. The envelope contains the full execution payload along with associated metadata. Depending on `Accept` header, it can be returned either as json or as bytes serialized by SSZ. tags: diff --git a/types/gloas/execution_payload_bid.yaml b/types/gloas/execution_payload_bid.yaml index 14ce0da4..653b57b6 100644 --- a/types/gloas/execution_payload_bid.yaml +++ b/types/gloas/execution_payload_bid.yaml @@ -1,7 +1,7 @@ Gloas: ExecutionPayloadBid: type: object - description: "The [`ExecutionPayloadBid`](https://github.com/ethereum/consensus-specs/blob/00d531949b1f30516979b60ddd2a411e7f388299/specs/gloas/beacon-chain.md#executionpayloadbid) object from the CL gloas spec." + description: "The [`ExecutionPayloadBid`](https://github.com/ethereum/consensus-specs/blob/00d531949b1f30516979b60ddd2a411e7f388299/specs/gloas/beacon-chain.md#executionpayloadbid) object from the CL Gloas spec." required: [parent_block_hash, parent_block_root, block_hash, fee_recipient, gas_limit, builder_index, slot, value, blob_kzg_commitments_root] properties: parent_block_hash: @@ -25,7 +25,7 @@ Gloas: SignedExecutionPayloadBid: type: object - description: "The [`SignedExecutionPayloadBid`](https://github.com/ethereum/consensus-specs/blob/00d531949b1f30516979b60ddd2a411e7f388299/specs/gloas/beacon-chain.md#signedexecutionpayloadbid) object from the CL gloas spec." + description: "The [`SignedExecutionPayloadBid`](https://github.com/ethereum/consensus-specs/blob/00d531949b1f30516979b60ddd2a411e7f388299/specs/gloas/beacon-chain.md#signedexecutionpayloadbid) object from the CL Gloas spec." required: [message, signature] properties: message: diff --git a/types/gloas/execution_payload_envelope.yaml b/types/gloas/execution_payload_envelope.yaml index 7baf80f0..546f8165 100644 --- a/types/gloas/execution_payload_envelope.yaml +++ b/types/gloas/execution_payload_envelope.yaml @@ -1,7 +1,7 @@ Gloas: ExecutionPayloadEnvelope: type: object - description: "The [`ExecutionPayloadEnvelope`](https://github.com/ethereum/consensus-specs/blob/00d531949b1f30516979b60ddd2a411e7f388299/specs/gloas/beacon-chain.md#executionpayloadenvelope) object from the CL gloas spec." + description: "The [`ExecutionPayloadEnvelope`](https://github.com/ethereum/consensus-specs/blob/00d531949b1f30516979b60ddd2a411e7f388299/specs/gloas/beacon-chain.md#executionpayloadenvelope) object from the CL Gloas spec." required: [payload, execution_requests, builder_index, beacon_block_root, slot, blob_kzg_commitments, state_root] properties: payload: @@ -30,7 +30,7 @@ Gloas: SignedExecutionPayloadEnvelope: type: object - description: "The [`SignedExecutionPayloadEnvelope`](https://github.com/ethereum/consensus-specs/blob/00d531949b1f30516979b60ddd2a411e7f388299/specs/gloas/beacon-chain.md#signedexecutionpayloadenvelope) object from the CL gloas spec." + description: "The [`SignedExecutionPayloadEnvelope`](https://github.com/ethereum/consensus-specs/blob/00d531949b1f30516979b60ddd2a411e7f388299/specs/gloas/beacon-chain.md#signedexecutionpayloadenvelope) object from the CL Gloas spec." required: [message, signature] properties: message: diff --git a/types/gloas/payload_attestation.yaml b/types/gloas/payload_attestation.yaml index 82eb5b7d..1ae0995d 100644 --- a/types/gloas/payload_attestation.yaml +++ b/types/gloas/payload_attestation.yaml @@ -19,7 +19,7 @@ Gloas: PayloadAttestation: type: object - description: "The [`PayloadAttestation`](https://github.com/ethereum/consensus-specs/blob/00d531949b1f30516979b60ddd2a411e7f388299/specs/gloas/beacon-chain.md#payloadattestation) object from the CL gloas spec." + description: "The [`PayloadAttestation`](https://github.com/ethereum/consensus-specs/blob/00d531949b1f30516979b60ddd2a411e7f388299/specs/gloas/beacon-chain.md#payloadattestation) object from the CL Gloas spec." required: [aggregation_bits, data, signature] properties: aggregation_bits: diff --git a/wordlist.txt b/wordlist.txt index d802300c..ea0d7401 100644 --- a/wordlist.txt +++ b/wordlist.txt @@ -38,3 +38,7 @@ KZGCommitmentInclusionProof LMD fulu gloas +PTC +ptc +PtcDuty +produceBlockV From 37eaf5c30ab3efc6cbdd22867930dcd687212ec3 Mon Sep 17 00:00:00 2001 From: shane-moore Date: Thu, 6 Nov 2025 08:07:16 -0800 Subject: [PATCH 21/42] add payload attestation and execution payload bid events --- apis/eventstream/index.yaml | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/apis/eventstream/index.yaml b/apis/eventstream/index.yaml index 0acf2df5..db0e5d3b 100644 --- a/apis/eventstream/index.yaml +++ b/apis/eventstream/index.yaml @@ -40,6 +40,8 @@ get: - blob_sidecar - data_column_sidecar - execution_payload_available + - execution_payload_bid + - payload_attestation responses: "200": description: Opened SSE stream. @@ -164,6 +166,16 @@ get: value: | event: execution_payload_available data: {"slot": "10", "block_root": "0x9a2fefd2fdb57f74993c7780ea5b9030d2897b615b89f808011ca5aebed54eaf"} + execution_payload_bid: + description: The node has received a `SignedExecutionPayloadBid` (from P2P or API) that passes gossip validation on the `execution_payload_bid` topic + value: | + event: execution_payload_bid + data: {"slot": "10", "builder_index": "42", "parent_block_root": "0x9a2fefd2fdb57f74993c7780ea5b9030d2897b615b89f808011ca5aebed54eaf", "block_hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", "value": "1000000000"} + payload_attestation: + description: The node has received a `PayloadAttestationMessage` that passes validation rules of the `payload_attestation` topic + value: | + event: payload_attestation + data: {"validator_index": "123", "slot": "10", "beacon_block_root": "0x9a2fefd2fdb57f74993c7780ea5b9030d2897b615b89f808011ca5aebed54eaf", "payload_present": true, "blob_data_available": true} "400": description: "The topics supplied could not be parsed" content: From 7bcc791ad652d9583fae7e37f23dcbce9cc5b886 Mon Sep 17 00:00:00 2001 From: Bharath Vedartham Date: Fri, 28 Nov 2025 20:01:32 +0530 Subject: [PATCH 22/42] add execution_payment to execution_payload_bid --- types/gloas/execution_payload_bid.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/types/gloas/execution_payload_bid.yaml b/types/gloas/execution_payload_bid.yaml index 653b57b6..6dad5dbf 100644 --- a/types/gloas/execution_payload_bid.yaml +++ b/types/gloas/execution_payload_bid.yaml @@ -20,6 +20,8 @@ Gloas: $ref: "../primitive.yaml#/Uint64" value: $ref: "../primitive.yaml#/Gwei" + execution_payment: + $ref: "../primitive.yaml#/Gwei" blob_kzg_commitments_root: $ref: "../primitive.yaml#/Root" From fe362694bd70685fe7d24cc40ada99178a354d7d Mon Sep 17 00:00:00 2001 From: shane-moore Date: Mon, 29 Dec 2025 19:51:08 -0800 Subject: [PATCH 23/42] add payload attestation and bid fields for eventstream --- apis/eventstream/index.yaml | 12 ++++++------ types/gloas/execution_payload_bid.yaml | 2 +- types/gloas/payload_attestation.yaml | 2 +- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/apis/eventstream/index.yaml b/apis/eventstream/index.yaml index db0e5d3b..d9c7d8fe 100644 --- a/apis/eventstream/index.yaml +++ b/apis/eventstream/index.yaml @@ -41,7 +41,7 @@ get: - data_column_sidecar - execution_payload_available - execution_payload_bid - - payload_attestation + - payload_attestation_message responses: "200": description: Opened SSE stream. @@ -170,12 +170,12 @@ get: description: The node has received a `SignedExecutionPayloadBid` (from P2P or API) that passes gossip validation on the `execution_payload_bid` topic value: | event: execution_payload_bid - data: {"slot": "10", "builder_index": "42", "parent_block_root": "0x9a2fefd2fdb57f74993c7780ea5b9030d2897b615b89f808011ca5aebed54eaf", "block_hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", "value": "1000000000"} - payload_attestation: - description: The node has received a `PayloadAttestationMessage` that passes validation rules of the `payload_attestation` topic + data: {"message": {"parent_block_hash": "0x9a2fefd2fdb57f74993c7780ea5b9030d2897b615b89f808011ca5aebed54eaf", "parent_block_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", "block_hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", "prev_randao": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", "fee_recipient": "0x0000000000000000000000000000000000000000", "gas_limit": "30000000", "builder_index": "42", "slot": "10", "value": "1000000000", "execution_payment": "0", "blob_kzg_commitments_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2"}, "signature": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505"} + payload_attestation_message: + description: The node has received a `PayloadAttestationMessage` that passes validation rules of the `payload_attestation_message` topic value: | - event: payload_attestation - data: {"validator_index": "123", "slot": "10", "beacon_block_root": "0x9a2fefd2fdb57f74993c7780ea5b9030d2897b615b89f808011ca5aebed54eaf", "payload_present": true, "blob_data_available": true} + event: payload_attestation_message + data: {"validator_index": "123", "data": {"beacon_block_root": "0x9a2fefd2fdb57f74993c7780ea5b9030d2897b615b89f808011ca5aebed54eaf", "slot": "10", "payload_present": true, "blob_data_available": true}, "signature": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505"} "400": description: "The topics supplied could not be parsed" content: diff --git a/types/gloas/execution_payload_bid.yaml b/types/gloas/execution_payload_bid.yaml index 6dad5dbf..e500bdd2 100644 --- a/types/gloas/execution_payload_bid.yaml +++ b/types/gloas/execution_payload_bid.yaml @@ -2,7 +2,7 @@ Gloas: ExecutionPayloadBid: type: object description: "The [`ExecutionPayloadBid`](https://github.com/ethereum/consensus-specs/blob/00d531949b1f30516979b60ddd2a411e7f388299/specs/gloas/beacon-chain.md#executionpayloadbid) object from the CL Gloas spec." - required: [parent_block_hash, parent_block_root, block_hash, fee_recipient, gas_limit, builder_index, slot, value, blob_kzg_commitments_root] + required: [parent_block_hash, parent_block_root, block_hash, fee_recipient, gas_limit, builder_index, slot, value, execution_payment, blob_kzg_commitments_root] properties: parent_block_hash: $ref: "../primitive.yaml#/Root" diff --git a/types/gloas/payload_attestation.yaml b/types/gloas/payload_attestation.yaml index 1ae0995d..2e5dc65b 100644 --- a/types/gloas/payload_attestation.yaml +++ b/types/gloas/payload_attestation.yaml @@ -23,7 +23,7 @@ Gloas: required: [aggregation_bits, data, signature] properties: aggregation_bits: - $ref: "../primitive.yaml#/BitList" + $ref: "../primitive.yaml#/Bitvector" data: $ref: "#/Gloas/PayloadAttestationData" signature: From de0d74030ea7e0a8315617957efdf3d90c8899d1 Mon Sep 17 00:00:00 2001 From: Nico Flaig Date: Mon, 26 Jan 2026 14:36:15 +0100 Subject: [PATCH 24/42] Add prev_randao to execution payload bid --- types/gloas/execution_payload_bid.yaml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/types/gloas/execution_payload_bid.yaml b/types/gloas/execution_payload_bid.yaml index e500bdd2..da4cbc30 100644 --- a/types/gloas/execution_payload_bid.yaml +++ b/types/gloas/execution_payload_bid.yaml @@ -2,7 +2,7 @@ Gloas: ExecutionPayloadBid: type: object description: "The [`ExecutionPayloadBid`](https://github.com/ethereum/consensus-specs/blob/00d531949b1f30516979b60ddd2a411e7f388299/specs/gloas/beacon-chain.md#executionpayloadbid) object from the CL Gloas spec." - required: [parent_block_hash, parent_block_root, block_hash, fee_recipient, gas_limit, builder_index, slot, value, execution_payment, blob_kzg_commitments_root] + required: [parent_block_hash, parent_block_root, block_hash, prev_randao, fee_recipient, gas_limit, builder_index, slot, value, execution_payment, blob_kzg_commitments_root] properties: parent_block_hash: $ref: "../primitive.yaml#/Root" @@ -10,6 +10,8 @@ Gloas: $ref: "../primitive.yaml#/Root" block_hash: $ref: "../primitive.yaml#/Root" + prev_randao: + $ref: "../primitive.yaml#/Root" fee_recipient: $ref: "../primitive.yaml#/ExecutionAddress" gas_limit: From e12bf98dbe9bf65e0eb3b03a9a6d71c027bacea6 Mon Sep 17 00:00:00 2001 From: Nico Flaig Date: Mon, 26 Jan 2026 18:56:22 +0100 Subject: [PATCH 25/42] Make builders non-validating staked actors --- apis/validator/execution_payload_bid.yaml | 2 +- apis/validator/execution_payload_envelope.yaml | 2 +- validator-flow.md | 5 +++-- 3 files changed, 5 insertions(+), 4 deletions(-) diff --git a/apis/validator/execution_payload_bid.yaml b/apis/validator/execution_payload_bid.yaml index 9f129481..3dee04da 100644 --- a/apis/validator/execution_payload_bid.yaml +++ b/apis/validator/execution_payload_bid.yaml @@ -54,7 +54,7 @@ get: InvalidBuilderIndex: value: code: 400 - message: "Builder index does not correspond to a registered builder validator" + message: "Builder index does not correspond to a registered builder" "404": description: "Execution payload bid not available for the requested slot and builder" content: diff --git a/apis/validator/execution_payload_envelope.yaml b/apis/validator/execution_payload_envelope.yaml index d6463b1c..6ed1fd3f 100644 --- a/apis/validator/execution_payload_envelope.yaml +++ b/apis/validator/execution_payload_envelope.yaml @@ -18,7 +18,7 @@ get: - name: builder_index in: path required: true - description: "Validator index of the builder from which the execution payload envelope is requested. For self-building, it will be the proposer's validator index." + description: "Validator index of the builder from which the execution payload envelope is requested. For self-building, it will be `BUILDER_INDEX_SELF_BUILD`." schema: $ref: "../../beacon-node-oapi.yaml#/components/schemas/Uint64" responses: diff --git a/validator-flow.md b/validator-flow.md index 8d47db17..41909ce7 100644 --- a/validator-flow.md +++ b/validator-flow.md @@ -76,8 +76,9 @@ If reorg is detected, ask for new PTC duties and proceed from 1.. ### Builder (Optional) -Post-Gloas fork, validators may optionally act as builders to submit execution payload bids for block inclusion. -This requires registering with builder-specific withdrawal credentials (`BUILDER_WITHDRAWAL_PREFIX`). +Post-Gloas fork, builders are separate non-validating staked actors that submit execution payload bids for block inclusion. +Builders register by depositing with builder-specific withdrawal credentials (`BUILDER_WITHDRAWAL_PREFIX`) and are tracked +in the beacon state's builder registry. Building: 1. [Fetch ExecutionPayloadBid](#/Validator/getExecutionPayloadBid) from beacon node for the current or next slot's proposer to include. From 97f582fc338ce3e625e9c651f7599a53181ad179 Mon Sep 17 00:00:00 2001 From: Nico Flaig Date: Tue, 27 Jan 2026 15:39:10 +0100 Subject: [PATCH 26/42] Apply suggestion from @nflaig --- apis/validator/execution_payload_envelope.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apis/validator/execution_payload_envelope.yaml b/apis/validator/execution_payload_envelope.yaml index 6ed1fd3f..3a1a2a5a 100644 --- a/apis/validator/execution_payload_envelope.yaml +++ b/apis/validator/execution_payload_envelope.yaml @@ -18,7 +18,7 @@ get: - name: builder_index in: path required: true - description: "Validator index of the builder from which the execution payload envelope is requested. For self-building, it will be `BUILDER_INDEX_SELF_BUILD`." + description: "Index of the builder from which the execution payload envelope is requested. For self-building, it will be `BUILDER_INDEX_SELF_BUILD`." schema: $ref: "../../beacon-node-oapi.yaml#/components/schemas/Uint64" responses: From e697311c5b4086c7cfbe73e56249fa9cd4f0242d Mon Sep 17 00:00:00 2001 From: Nico Flaig Date: Mon, 9 Feb 2026 11:29:27 +0000 Subject: [PATCH 27/42] Review PR --- apis/beacon/blocks/blocks.v2.yaml | 5 +++-- apis/eventstream/index.yaml | 2 +- types/gloas/execution_payload_bid.yaml | 8 +++++--- types/gloas/execution_payload_envelope.yaml | 9 +-------- 4 files changed, 10 insertions(+), 14 deletions(-) diff --git a/apis/beacon/blocks/blocks.v2.yaml b/apis/beacon/blocks/blocks.v2.yaml index e96562a1..b93e6db9 100644 --- a/apis/beacon/blocks/blocks.v2.yaml +++ b/apis/beacon/blocks/blocks.v2.yaml @@ -12,8 +12,9 @@ post: before doing so, so as to aid timely delivery of the block. Should the block fail full validation, a separate success response code (202) is used to indicate that the block was successfully broadcast but failed integration. For Deneb/Electra/Fulu, this additionally instructs - the beacon node to broadcast all given blobs. The broadcast behaviour may be adjusted via the - `broadcast_validation` query parameter. + the beacon node to broadcast all given blobs. For Gloas and later, blobs are broadcast as part + of the `ExecutionPayloadEnvelope` and are not submitted with the block. The broadcast behaviour + may be adjusted via the `broadcast_validation` query parameter. parameters: - name: broadcast_validation in: query diff --git a/apis/eventstream/index.yaml b/apis/eventstream/index.yaml index d9c7d8fe..8f8d2298 100644 --- a/apis/eventstream/index.yaml +++ b/apis/eventstream/index.yaml @@ -170,7 +170,7 @@ get: description: The node has received a `SignedExecutionPayloadBid` (from P2P or API) that passes gossip validation on the `execution_payload_bid` topic value: | event: execution_payload_bid - data: {"message": {"parent_block_hash": "0x9a2fefd2fdb57f74993c7780ea5b9030d2897b615b89f808011ca5aebed54eaf", "parent_block_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", "block_hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", "prev_randao": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", "fee_recipient": "0x0000000000000000000000000000000000000000", "gas_limit": "30000000", "builder_index": "42", "slot": "10", "value": "1000000000", "execution_payment": "0", "blob_kzg_commitments_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2"}, "signature": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505"} + data: {"message": {"parent_block_hash": "0x9a2fefd2fdb57f74993c7780ea5b9030d2897b615b89f808011ca5aebed54eaf", "parent_block_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", "block_hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", "prev_randao": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", "fee_recipient": "0x0000000000000000000000000000000000000000", "gas_limit": "30000000", "builder_index": "42", "slot": "10", "value": "1000000000", "execution_payment": "0", "blob_kzg_commitments": ["0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2"]}, "signature": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505"} payload_attestation_message: description: The node has received a `PayloadAttestationMessage` that passes validation rules of the `payload_attestation_message` topic value: | diff --git a/types/gloas/execution_payload_bid.yaml b/types/gloas/execution_payload_bid.yaml index da4cbc30..8861bf9f 100644 --- a/types/gloas/execution_payload_bid.yaml +++ b/types/gloas/execution_payload_bid.yaml @@ -2,7 +2,7 @@ Gloas: ExecutionPayloadBid: type: object description: "The [`ExecutionPayloadBid`](https://github.com/ethereum/consensus-specs/blob/00d531949b1f30516979b60ddd2a411e7f388299/specs/gloas/beacon-chain.md#executionpayloadbid) object from the CL Gloas spec." - required: [parent_block_hash, parent_block_root, block_hash, prev_randao, fee_recipient, gas_limit, builder_index, slot, value, execution_payment, blob_kzg_commitments_root] + required: [parent_block_hash, parent_block_root, block_hash, prev_randao, fee_recipient, gas_limit, builder_index, slot, value, execution_payment, blob_kzg_commitments] properties: parent_block_hash: $ref: "../primitive.yaml#/Root" @@ -24,8 +24,10 @@ Gloas: $ref: "../primitive.yaml#/Gwei" execution_payment: $ref: "../primitive.yaml#/Gwei" - blob_kzg_commitments_root: - $ref: "../primitive.yaml#/Root" + blob_kzg_commitments: + type: array + items: + $ref: '../primitive.yaml#/KZGCommitment' SignedExecutionPayloadBid: type: object diff --git a/types/gloas/execution_payload_envelope.yaml b/types/gloas/execution_payload_envelope.yaml index 546f8165..f006ac8b 100644 --- a/types/gloas/execution_payload_envelope.yaml +++ b/types/gloas/execution_payload_envelope.yaml @@ -2,7 +2,7 @@ Gloas: ExecutionPayloadEnvelope: type: object description: "The [`ExecutionPayloadEnvelope`](https://github.com/ethereum/consensus-specs/blob/00d531949b1f30516979b60ddd2a411e7f388299/specs/gloas/beacon-chain.md#executionpayloadenvelope) object from the CL Gloas spec." - required: [payload, execution_requests, builder_index, beacon_block_root, slot, blob_kzg_commitments, state_root] + required: [payload, execution_requests, builder_index, beacon_block_root, slot, state_root] properties: payload: $ref: "../deneb/execution_payload.yaml#/Deneb/ExecutionPayload" @@ -17,13 +17,6 @@ Gloas: slot: $ref: "../primitive.yaml#/Uint64" description: "Slot number for this execution payload" - blob_kzg_commitments: - type: array - items: - $ref: "../primitive.yaml#/KZGCommitment" - minItems: 0 - maxItems: 4096 - description: "KZG commitments for the blobs included in this execution payload" state_root: $ref: "../primitive.yaml#/Root" description: "Beacon state root after executing this payload" From 9c2acdee7a074835856b4988486edc2666f67319 Mon Sep 17 00:00:00 2001 From: shane-moore Date: Wed, 4 Feb 2026 19:26:00 -0500 Subject: [PATCH 28/42] chore: remove produceBlockV4 --- CHANGES.md | 1 - apis/validator/block.v4.yaml | 111 ----------------------------------- beacon-node-oapi.yaml | 2 - validator-flow.md | 5 +- 4 files changed, 2 insertions(+), 117 deletions(-) delete mode 100644 apis/validator/block.v4.yaml diff --git a/CHANGES.md b/CHANGES.md index fbd7e46d..606d3aef 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -16,7 +16,6 @@ There are likely to be descriptions etc outside of the list below, but new query | [#552](https://github.com/ethereum/beacon-APIs/pull/552) `GET /eth/v1/beacon/execution_payload_envelope/{block_id}` added | | | | | | | [#552](https://github.com/ethereum/beacon-APIs/pull/552) `POST /eth/v1/beacon/execution_payload_envelope` added | | | | | | | [#552](https://github.com/ethereum/beacon-APIs/pull/552) `POST /eth/v1/beacon/pool/payload_attestations` added | | | | | | -| [#552](https://github.com/ethereum/beacon-APIs/pull/552) `GET /eth/v4/validator/blocks/{slot}` added | | | | | | | [#552](https://github.com/ethereum/beacon-APIs/pull/552) `POST /eth/v2/beacon/blocks` updated | | | | | | The Following are no longer in the Standard API, removed since the latest version. diff --git a/apis/validator/block.v4.yaml b/apis/validator/block.v4.yaml deleted file mode 100644 index f53f4241..00000000 --- a/apis/validator/block.v4.yaml +++ /dev/null @@ -1,111 +0,0 @@ -get: - tags: - - Validator - - ValidatorRequiredApi - operationId: "produceBlockV4" - summary: "Produce a new block, without signature." - description: | - Requests a beacon node to produce a valid block, which can then be signed by a validator. - - 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. - 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: builder_boost_factor - in: query - required: false - description: | - Percentage multiplier to apply to the builder's payload value when choosing between a - builder payload header and payload from the paired execution node. This parameter is only - relevant if the beacon node is connected to a builder, deems it safe to produce a builder - payload, and receives valid responses from both the builder endpoint _and_ 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 full (unblinded) block containing the execution node payload. - * otherwise, return a blinded block containing the builder payload header. - - 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 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 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" - 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' - content: - application/json: - schema: - title: "ProduceBlockV4Response" - type: object - required: [version, consensus_block_value, data] - properties: - version: - type: string - enum: [gloas] - example: "gloas" - consensus_block_value: - type: string - example: "12345" - description: "Consensus rewards for this block in Wei" - data: - $ref: "../../beacon-node-oapi.yaml#/components/schemas/Gloas.BeaconBlock" - application/octet-stream: - schema: - description: "SSZ serialized `BeaconBlock` bytes. Use Accept header to choose this response type, version string is sent in header `Eth-Consensus-Version`." - "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" - "500": - $ref: '../../beacon-node-oapi.yaml#/components/responses/InternalError' - "503": - $ref: '../../beacon-node-oapi.yaml#/components/responses/CurrentlySyncing' diff --git a/beacon-node-oapi.yaml b/beacon-node-oapi.yaml index dc612d42..5f3526de 100644 --- a/beacon-node-oapi.yaml +++ b/beacon-node-oapi.yaml @@ -192,8 +192,6 @@ paths: $ref: "./apis/validator/duties/ptc.yaml" /eth/v3/validator/blocks/{slot}: $ref: "./apis/validator/block.v3.yaml" - /eth/v4/validator/blocks/{slot}: - $ref: "./apis/validator/block.v4.yaml" /eth/v1/validator/attestation_data: $ref: "./apis/validator/attestation_data.yaml" /eth/v1/validator/payload_attestation_data/{slot}: diff --git a/validator-flow.md b/validator-flow.md index 41909ce7..2e5d52ee 100644 --- a/validator-flow.md +++ b/validator-flow.md @@ -15,9 +15,8 @@ On start of every epoch, validator should [fetch proposer duties](#/Validator/ge Result is array of objects, each containing proposer pubkey and slot at which he is suppose to propose. If proposing block, then at immediate start of slot: -1. Ask Beacon Node for BeaconBlock object: - - Pre-Gloas forks: [produceBlockV3](#/Validator/produceBlockV3) - - Post-Gloas fork: [produceBlockV4](#/Validator/produceBlockV4) +1. Ask Beacon Node for BeaconBlock object: [produceBlockV3](#/Validator/produceBlockV3) + - TODO: Post-Gloas block production endpoint (produceBlockV4) to be added in separate PR 2. Sign block 3. [Submit SignedBeaconBlock](#/ValidatorRequiredApi/publishBlock) (BeaconBlock + signature) 4. Post-Gloas, if self-building (proposer's own bid included in block): From bd9a3c89280661b13e285789cf82b38ed4ceac70 Mon Sep 17 00:00:00 2001 From: shane-moore Date: Mon, 9 Feb 2026 20:20:16 -0800 Subject: [PATCH 29/42] remove envelope endpoints --- .../execution_payload/envelope_post.yaml | 43 ------------ .../validator/execution_payload_envelope.yaml | 67 ------------------- beacon-node-oapi.yaml | 4 -- validator-flow.md | 10 +-- 4 files changed, 2 insertions(+), 122 deletions(-) delete mode 100644 apis/beacon/execution_payload/envelope_post.yaml delete mode 100644 apis/validator/execution_payload_envelope.yaml diff --git a/apis/beacon/execution_payload/envelope_post.yaml b/apis/beacon/execution_payload/envelope_post.yaml deleted file mode 100644 index 0b3ac276..00000000 --- a/apis/beacon/execution_payload/envelope_post.yaml +++ /dev/null @@ -1,43 +0,0 @@ -post: - operationId: publishExecutionPayloadEnvelope - summary: Publish signed execution payload envelope - description: | - Instructs the beacon node to broadcast a signed execution payload envelope to the network, - to be gossiped for payload validation. A success response (20x) indicates - that the envelope passed gossip validation and was successfully broadcast onto the network. - tags: - - Beacon - - ValidatorRequiredApi - 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 execution payload envelope being submitted belongs." - requestBody: - description: "The `SignedExecutionPayloadEnvelope` object to be broadcast." - required: true - content: - application/json: - schema: - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Gloas.SignedExecutionPayloadEnvelope" - application/octet-stream: - schema: - description: "SSZ serialized `SignedExecutionPayloadEnvelope` bytes. Use Content-Type header to specify this format" - responses: - "200": - description: "The envelope was validated successfully and has been broadcast." - "400": - description: "The SignedExecutionPayloadEnvelope object is invalid or failed gossip validation" - content: - application/json: - schema: - $ref: "../../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage" - example: - code: 400 - message: "Invalid signed execution payload envelope" - "415": - $ref: "../../../beacon-node-oapi.yaml#/components/responses/UnsupportedMediaType" - "500": - $ref: "../../../beacon-node-oapi.yaml#/components/responses/InternalError" diff --git a/apis/validator/execution_payload_envelope.yaml b/apis/validator/execution_payload_envelope.yaml deleted file mode 100644 index 3a1a2a5a..00000000 --- a/apis/validator/execution_payload_envelope.yaml +++ /dev/null @@ -1,67 +0,0 @@ -get: - operationId: getExecutionPayloadEnvelope - summary: Get execution payload envelope - description: | - Retrieves execution payload envelope for a given slot and builder, which can then be signed by a validator. The envelope contains the full - execution payload along with associated metadata. Depending on `Accept` header, it can be returned - either as json or as bytes serialized by SSZ. - tags: - - Validator - - ValidatorRequiredApi - parameters: - - name: slot - in: path - required: true - description: "Slot for which the execution payload envelope is requested." - schema: - $ref: "../../beacon-node-oapi.yaml#/components/schemas/Uint64" - - name: builder_index - in: path - required: true - description: "Index of the builder from which the execution payload envelope is requested. For self-building, it will be `BUILDER_INDEX_SELF_BUILD`." - schema: - $ref: "../../beacon-node-oapi.yaml#/components/schemas/Uint64" - responses: - "200": - description: "Successful response" - headers: - Eth-Consensus-Version: - $ref: "../../beacon-node-oapi.yaml#/components/headers/Eth-Consensus-Version" - content: - application/json: - schema: - title: GetExecutionPayloadEnvelopeResponse - type: object - required: [version, data] - properties: - version: - type: string - enum: [gloas] - example: "gloas" - data: - $ref: "../../beacon-node-oapi.yaml#/components/schemas/Gloas.ExecutionPayloadEnvelope" - application/octet-stream: - schema: - description: "SSZ serialized `ExecutionPayloadEnvelope` bytes. Use Accept header to choose this response type" - "400": - description: "Invalid execution payload envelope request" - content: - application/json: - schema: - $ref: "../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage" - example: - code: 400 - message: "Invalid slot or builder_index parameter" - "404": - description: "Execution payload envelope not available for the requested slot and builder" - content: - application/json: - schema: - $ref: "../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage" - example: - code: 404 - message: "Execution payload envelope not available for slot and builder" - "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 5f3526de..240ba4b8 100644 --- a/beacon-node-oapi.yaml +++ b/beacon-node-oapi.yaml @@ -106,8 +106,6 @@ paths: $ref: "./apis/beacon/blocks/blocks.v2.yaml" /eth/v1/beacon/execution_payload_bid: $ref: "./apis/beacon/execution_payload/bid.yaml" - /eth/v1/beacon/execution_payload_envelope: - $ref: "./apis/beacon/execution_payload/envelope_post.yaml" /eth/v1/beacon/execution_payload_envelope/{block_id}: $ref: "./apis/beacon/execution_payload/envelope_get.yaml" /eth/v2/beacon/blocks/{block_id}: @@ -220,8 +218,6 @@ paths: $ref: "./apis/validator/liveness.yaml" /eth/v1/validator/execution_payload_bid/{slot}/{builder_index}: $ref: "./apis/validator/execution_payload_bid.yaml" - /eth/v1/validator/execution_payload_envelope/{slot}/{builder_index}: - $ref: "./apis/validator/execution_payload_envelope.yaml" /eth/v1/events: $ref: "./apis/eventstream/index.yaml" diff --git a/validator-flow.md b/validator-flow.md index 2e5d52ee..7c006f3c 100644 --- a/validator-flow.md +++ b/validator-flow.md @@ -19,10 +19,7 @@ If proposing block, then at immediate start of slot: - TODO: Post-Gloas block production endpoint (produceBlockV4) to be added in separate PR 2. Sign block 3. [Submit SignedBeaconBlock](#/ValidatorRequiredApi/publishBlock) (BeaconBlock + signature) -4. Post-Gloas, if self-building (proposer's own bid included in block): - - [Fetch ExecutionPayloadEnvelope](#/Validator/getExecutionPayloadEnvelope) from beacon node - - Sign envelope and [submit SignedExecutionPayloadEnvelope](#/Beacon/publishExecutionPayloadEnvelope) - - Must submit early enough for PTC attestation by [PAYLOAD_ATTESTATION_DUE_BPS](https://github.com/ethereum/consensus-specs/blob/00d531949b1f30516979b60ddd2a411e7f388299/specs/gloas/validator.md#time-parameters) of slot duration +4. TODO: Post-Gloas local block building flow (stateless vs. stateful) to be detailed in separate PR Monitor chain block reorganization events (TBD) as they could change block proposers. If reorg is detected, ask for new proposer duties and proceed from 1. @@ -85,10 +82,7 @@ Building: 2. Cache fields required to form an [ExecutionPayloadEnvelope](https://github.com/ethereum/consensus-specs/blob/00d531949b1f30516979b60ddd2a411e7f388299/specs/gloas/beacon-chain.md#executionpayloadenvelope) 2. Sign ExecutionPayloadBid to create SignedExecutionPayloadBid 3. [Submit SignedExecutionPayloadBid](#/Beacon/publishExecutionPayloadBid) to network for proposer consideration -4. If bid is selected by proposer in their block: - - [Fetch ExecutionPayloadEnvelope](#/Validator/getExecutionPayloadEnvelope) from beacon node - - Sign envelope and [submit SignedExecutionPayloadEnvelope](#/Beacon/publishExecutionPayloadEnvelope) - - Must submit early enough for PTC attestation by [PAYLOAD_ATTESTATION_DUE_BPS](https://github.com/ethereum/consensus-specs/blob/00d531949b1f30516979b60ddd2a411e7f388299/specs/gloas/validator.md#time-parameters) of slot duration +4. TODO: Envelope fetching and publishing flow (stateless vs. stateful) to be detailed in separate PR Monitor for block proposals containing your bid to trigger envelope release. From 1aafd356fa3abf1da944fcf8c593a52d03bb8102 Mon Sep 17 00:00:00 2001 From: shane-moore Date: Mon, 9 Feb 2026 20:39:19 -0800 Subject: [PATCH 30/42] chore: updates per pr review --- apis/validator/attestation_data.yaml | 14 ++++++++++---- apis/validator/block.v3.yaml | 2 +- 2 files changed, 11 insertions(+), 5 deletions(-) diff --git a/apis/validator/attestation_data.yaml b/apis/validator/attestation_data.yaml index b25f71e1..d6407c72 100644 --- a/apis/validator/attestation_data.yaml +++ b/apis/validator/attestation_data.yaml @@ -5,8 +5,12 @@ get: operationId: "produceAttestationData" summary: "Produce an attestation data" description: | - Requests that the beacon node produce an AttestationData. For `slot`s in - Electra and Fulu, this AttestationData must have a `committee_index` of 0. In Gloas, this `committee_index` field is repurposed to signal payload status: 0 if the execution payload is not present in the canonical chain (EMPTY), or 1 if the payload is present (FULL). For current slot attestations, which means the head block root is a block proposed in the same slot as the AttestationData.slot, always use 0. + Requests that the beacon node produce an `AttestationData`. + + For `slot`s in Electra and later, this `AttestationData` must have an `index` of `0`. + + For `slot`s in Gloas and later, the `index` in `AttestationData` is used to signal + payload availability which is determined and set by the beacon node. A 503 error must be returned if the block identified by the response `beacon_block_root` is optimistic (i.e. the attestation attests to a block @@ -20,10 +24,12 @@ get: $ref: ../../beacon-node-oapi.yaml#/components/schemas/Uint64 - name: committee_index in: query + deprecated: true description: | The committee index for which an attestation data should be created. For `slot`s in - Electra and Fulu, this parameter MAY always be set to 0. In Gloas, it signals payload status: 0 for EMPTY payload status, 1 for FULL payload status. - required: true + Electra and later, this parameter MAY always be set to 0. For `slot`s in Gloas and + later, this parameter MAY be omitted. + required: false schema: $ref: "../../beacon-node-oapi.yaml#/components/schemas/Uint64" responses: diff --git a/apis/validator/block.v3.yaml b/apis/validator/block.v3.yaml index 71a8e96f..6057bf53 100644 --- a/apis/validator/block.v3.yaml +++ b/apis/validator/block.v3.yaml @@ -14,7 +14,7 @@ get: header from an MEV relay. Metadata in the response indicates the type of block produced, and the supported types of block - are for all pre-Gloas forks. This endpoint is not forwards compatible after the Fulu fork. + are for all pre-Gloas forks. This endpoint is not forwards compatible after the Gloas fork. parameters: - name: slot in: path From 1e02d0a1394d5bd0e18372490f73119dca91092a Mon Sep 17 00:00:00 2001 From: shane-moore Date: Mon, 9 Feb 2026 20:56:54 -0800 Subject: [PATCH 31/42] chore: revert attestation_data changes to reflect master --- apis/validator/attestation_data.yaml | 14 ++++---------- 1 file changed, 4 insertions(+), 10 deletions(-) diff --git a/apis/validator/attestation_data.yaml b/apis/validator/attestation_data.yaml index d6407c72..0b62f277 100644 --- a/apis/validator/attestation_data.yaml +++ b/apis/validator/attestation_data.yaml @@ -5,12 +5,8 @@ get: operationId: "produceAttestationData" summary: "Produce an attestation data" description: | - Requests that the beacon node produce an `AttestationData`. - - For `slot`s in Electra and later, this `AttestationData` must have an `index` of `0`. - - For `slot`s in Gloas and later, the `index` in `AttestationData` is used to signal - payload availability which is determined and set by the beacon node. + Requests that the beacon node produce an AttestationData. For `slot`s in + Electra and later, this AttestationData must have a `committee_index` of 0. A 503 error must be returned if the block identified by the response `beacon_block_root` is optimistic (i.e. the attestation attests to a block @@ -24,12 +20,10 @@ get: $ref: ../../beacon-node-oapi.yaml#/components/schemas/Uint64 - name: committee_index in: query - deprecated: true description: | The committee index for which an attestation data should be created. For `slot`s in - Electra and later, this parameter MAY always be set to 0. For `slot`s in Gloas and - later, this parameter MAY be omitted. - required: false + Electra and later, this parameter MAY always be set to 0. + required: true schema: $ref: "../../beacon-node-oapi.yaml#/components/schemas/Uint64" responses: From 62aee323976e7572cc09222aa4fd408fb7de8bc9 Mon Sep 17 00:00:00 2001 From: shane-moore Date: Tue, 10 Feb 2026 13:13:30 -0800 Subject: [PATCH 32/42] remove payload endpoints from changelog --- CHANGES.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index 606d3aef..8e123100 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -9,12 +9,10 @@ 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) | |---------------------------------------------------------------------------------------------------------------------|--------------------------------------------------|---------------------------------------------------|----------------------------------------------------|-------------------------------------------------|-------------------------------------------| | [#552](https://github.com/ethereum/beacon-APIs/pull/552) `GET /eth/v1/validator/execution_payload_bid/{slot}/{builder_index}` added | | | | | | -| [#552](https://github.com/ethereum/beacon-APIs/pull/552) `GET /eth/v1/validator/execution_payload_envelope/{slot}/{builder_index}` added | | | | | | | [#552](https://github.com/ethereum/beacon-APIs/pull/552) `GET /eth/v1/validator/payload_attestation_data` added | | | | | | | [#552](https://github.com/ethereum/beacon-APIs/pull/552) `POST /eth/v1/validator/duties/ptc/{epoch}` added | | | | | | | [#552](https://github.com/ethereum/beacon-APIs/pull/552) `POST /eth/v1/beacon/execution_payload_bid` added | | | | | | | [#552](https://github.com/ethereum/beacon-APIs/pull/552) `GET /eth/v1/beacon/execution_payload_envelope/{block_id}` added | | | | | | -| [#552](https://github.com/ethereum/beacon-APIs/pull/552) `POST /eth/v1/beacon/execution_payload_envelope` added | | | | | | | [#552](https://github.com/ethereum/beacon-APIs/pull/552) `POST /eth/v1/beacon/pool/payload_attestations` added | | | | | | | [#552](https://github.com/ethereum/beacon-APIs/pull/552) `POST /eth/v2/beacon/blocks` updated | | | | | | From 317e9d95379251415ee8910fe55836277025eb40 Mon Sep 17 00:00:00 2001 From: Nico Flaig Date: Wed, 11 Feb 2026 12:25:35 +0000 Subject: [PATCH 33/42] Update apis/beacon/execution_payload/bid.yaml --- apis/beacon/execution_payload/bid.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apis/beacon/execution_payload/bid.yaml b/apis/beacon/execution_payload/bid.yaml index e3608201..8e26b5c4 100644 --- a/apis/beacon/execution_payload/bid.yaml +++ b/apis/beacon/execution_payload/bid.yaml @@ -28,7 +28,7 @@ post: "200": description: "The bid was validated successfully and has been broadcast." "400": - description: "The SignedExecutionPayloadBid object is invalid or failed gossip validation" + description: "The `SignedExecutionPayloadBid` object is invalid or failed gossip validation" content: application/json: schema: From a0e5d77f77c665f9e47a507f49b3c890175afa05 Mon Sep 17 00:00:00 2001 From: Nico Flaig Date: Wed, 11 Feb 2026 12:25:51 +0000 Subject: [PATCH 34/42] Update apis/beacon/execution_payload/envelope_get.yaml --- apis/beacon/execution_payload/envelope_get.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apis/beacon/execution_payload/envelope_get.yaml b/apis/beacon/execution_payload/envelope_get.yaml index 574827e4..1838847c 100644 --- a/apis/beacon/execution_payload/envelope_get.yaml +++ b/apis/beacon/execution_payload/envelope_get.yaml @@ -33,7 +33,7 @@ get: $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Gloas.SignedExecutionPayloadEnvelope" application/octet-stream: schema: - description: "SSZ serialized execution payload envelope bytes. Use Accept header to choose this response type" + description: "SSZ serialized `SignedExecutionPayloadEnvelope` bytes. Use Accept header to choose this response type" "400": description: "The block ID supplied could not be parsed" content: From 9bedb00587c31940904bd0f452516e45663ec28f Mon Sep 17 00:00:00 2001 From: Nico Flaig Date: Wed, 11 Feb 2026 12:26:05 +0000 Subject: [PATCH 35/42] Update apis/validator/payload_attestation_data.yaml --- apis/validator/payload_attestation_data.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apis/validator/payload_attestation_data.yaml b/apis/validator/payload_attestation_data.yaml index 4fb35304..5aa3fee3 100644 --- a/apis/validator/payload_attestation_data.yaml +++ b/apis/validator/payload_attestation_data.yaml @@ -5,7 +5,7 @@ get: operationId: "producePayloadAttestationData" summary: "Produce payload attestation data" description: | - Requests that the beacon node produce a PayloadAttestationData. + Requests that the beacon node produce a `PayloadAttestationData`. This endpoint is used by PTC validators to obtain the data structure they need to attest to regarding payload presence and blob data availability for a specific slot. From fcf0d912897cfddeb1c9bd413c3aa59a54d1fa07 Mon Sep 17 00:00:00 2001 From: Nico Flaig Date: Wed, 11 Feb 2026 12:36:21 +0000 Subject: [PATCH 36/42] Add ssz support to getPoolPayloadAttestations response --- apis/beacon/pool/payload_attestations.yaml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/apis/beacon/pool/payload_attestations.yaml b/apis/beacon/pool/payload_attestations.yaml index 4a2dfced..873fdb03 100644 --- a/apis/beacon/pool/payload_attestations.yaml +++ b/apis/beacon/pool/payload_attestations.yaml @@ -31,6 +31,9 @@ get: type: array items: $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Gloas.PayloadAttestation" + application/octet-stream: + schema: + description: "SSZ serialized `List[PayloadAttestation, MAX_PAYLOAD_ATTESTATIONS]` bytes. Use Accept header to choose this response type" "400": description: "The slot could not be parsed" content: From 2196102673ab934e696fa1d88ca5bfcac40a6565 Mon Sep 17 00:00:00 2001 From: Nico Flaig Date: Wed, 11 Feb 2026 12:36:38 +0000 Subject: [PATCH 37/42] Update spec references to v1.7.0-alpha.2 --- beacon-node-oapi.yaml | 2 +- types/gloas/block.yaml | 6 +++--- types/gloas/execution_payload_bid.yaml | 4 ++-- types/gloas/execution_payload_envelope.yaml | 4 ++-- types/gloas/payload_attestation.yaml | 6 +++--- validator-flow.md | 9 ++++----- 6 files changed, 15 insertions(+), 16 deletions(-) diff --git a/beacon-node-oapi.yaml b/beacon-node-oapi.yaml index 7396eebc..1e5014de 100644 --- a/beacon-node-oapi.yaml +++ b/beacon-node-oapi.yaml @@ -27,7 +27,7 @@ info: Note that it is possible for a field to be added to an endpoint's data or metadata without an increase in the version number. - version: "Dev - Ethereum Proof-of-Stake Consensus Specification v1.5.0" + version: "Dev - Ethereum Proof-of-Stake Consensus Specification v1.7.0-alpha.2" contact: name: Ethereum Github url: https://github.com/ethereum/beacon-apis/issues diff --git a/types/gloas/block.yaml b/types/gloas/block.yaml index 6c4bea95..6a026db5 100644 --- a/types/gloas/block.yaml +++ b/types/gloas/block.yaml @@ -1,7 +1,7 @@ Gloas: BeaconBlockBody: type: object - description: "The [`BeaconBlockBody`](https://github.com/ethereum/consensus-specs/blob/00d531949b1f30516979b60ddd2a411e7f388299/specs/gloas/beacon-chain.md#beaconblockbody) object from the CL Gloas spec." + description: "The [`BeaconBlockBody`](https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.2/specs/gloas/beacon-chain.md#beaconblockbody) object from the CL Gloas spec." required: [randao_reveal, eth1_data, graffiti, proposer_slashings, attester_slashings, attestations, deposits, voluntary_exits, sync_aggregate, bls_to_execution_changes, signed_execution_payload_bid, payload_attestations] properties: randao_reveal: @@ -48,7 +48,7 @@ Gloas: maxItems: 4 BeaconBlock: - description: "The [`BeaconBlock`](https://github.com/ethereum/consensus-specs/blob/v1.5.0/specs/phase0/beacon-chain.md#beaconblock) object from the CL Gloas spec." + description: "The [`BeaconBlock`](https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.2/specs/phase0/beacon-chain.md#beaconblock) object from the CL Gloas spec." allOf: - $ref: "../altair/block.yaml#/Altair/BeaconBlockCommon" - type: object @@ -59,7 +59,7 @@ Gloas: SignedBeaconBlock: type: object - description: "The [`SignedBeaconBlock`](https://github.com/ethereum/consensus-specs/blob/v1.5.0/specs/phase0/beacon-chain.md#signedbeaconblock) object envelope from the CL Gloas spec." + description: "The [`SignedBeaconBlock`](https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.2/specs/phase0/beacon-chain.md#signedbeaconblock) object envelope from the CL Gloas spec." required: [message, signature] properties: message: diff --git a/types/gloas/execution_payload_bid.yaml b/types/gloas/execution_payload_bid.yaml index 8861bf9f..e8818060 100644 --- a/types/gloas/execution_payload_bid.yaml +++ b/types/gloas/execution_payload_bid.yaml @@ -1,7 +1,7 @@ Gloas: ExecutionPayloadBid: type: object - description: "The [`ExecutionPayloadBid`](https://github.com/ethereum/consensus-specs/blob/00d531949b1f30516979b60ddd2a411e7f388299/specs/gloas/beacon-chain.md#executionpayloadbid) object from the CL Gloas spec." + description: "The [`ExecutionPayloadBid`](https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.2/specs/gloas/beacon-chain.md#executionpayloadbid) object from the CL Gloas spec." required: [parent_block_hash, parent_block_root, block_hash, prev_randao, fee_recipient, gas_limit, builder_index, slot, value, execution_payment, blob_kzg_commitments] properties: parent_block_hash: @@ -31,7 +31,7 @@ Gloas: SignedExecutionPayloadBid: type: object - description: "The [`SignedExecutionPayloadBid`](https://github.com/ethereum/consensus-specs/blob/00d531949b1f30516979b60ddd2a411e7f388299/specs/gloas/beacon-chain.md#signedexecutionpayloadbid) object from the CL Gloas spec." + description: "The [`SignedExecutionPayloadBid`](https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.2/specs/gloas/beacon-chain.md#signedexecutionpayloadbid) object from the CL Gloas spec." required: [message, signature] properties: message: diff --git a/types/gloas/execution_payload_envelope.yaml b/types/gloas/execution_payload_envelope.yaml index f006ac8b..2f8e6c32 100644 --- a/types/gloas/execution_payload_envelope.yaml +++ b/types/gloas/execution_payload_envelope.yaml @@ -1,7 +1,7 @@ Gloas: ExecutionPayloadEnvelope: type: object - description: "The [`ExecutionPayloadEnvelope`](https://github.com/ethereum/consensus-specs/blob/00d531949b1f30516979b60ddd2a411e7f388299/specs/gloas/beacon-chain.md#executionpayloadenvelope) object from the CL Gloas spec." + description: "The [`ExecutionPayloadEnvelope`](https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.2/specs/gloas/beacon-chain.md#executionpayloadenvelope) object from the CL Gloas spec." required: [payload, execution_requests, builder_index, beacon_block_root, slot, state_root] properties: payload: @@ -23,7 +23,7 @@ Gloas: SignedExecutionPayloadEnvelope: type: object - description: "The [`SignedExecutionPayloadEnvelope`](https://github.com/ethereum/consensus-specs/blob/00d531949b1f30516979b60ddd2a411e7f388299/specs/gloas/beacon-chain.md#signedexecutionpayloadenvelope) object from the CL Gloas spec." + description: "The [`SignedExecutionPayloadEnvelope`](https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.2/specs/gloas/beacon-chain.md#signedexecutionpayloadenvelope) object from the CL Gloas spec." required: [message, signature] properties: message: diff --git a/types/gloas/payload_attestation.yaml b/types/gloas/payload_attestation.yaml index 2e5dc65b..aa88697a 100644 --- a/types/gloas/payload_attestation.yaml +++ b/types/gloas/payload_attestation.yaml @@ -1,7 +1,7 @@ Gloas: PayloadAttestationData: type: object - description: "The [`PayloadAttestationData`](https://github.com/ethereum/consensus-specs/blob/00d531949b1f30516979b60ddd2a411e7f388299/specs/gloas/beacon-chain.md#payloadattestationdata) object from the CL Gloas spec." + description: "The [`PayloadAttestationData`](https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.2/specs/gloas/beacon-chain.md#payloadattestationdata) object from the CL Gloas spec." required: [beacon_block_root, slot, payload_present, blob_data_available] properties: beacon_block_root: @@ -19,7 +19,7 @@ Gloas: PayloadAttestation: type: object - description: "The [`PayloadAttestation`](https://github.com/ethereum/consensus-specs/blob/00d531949b1f30516979b60ddd2a411e7f388299/specs/gloas/beacon-chain.md#payloadattestation) object from the CL Gloas spec." + description: "The [`PayloadAttestation`](https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.2/specs/gloas/beacon-chain.md#payloadattestation) object from the CL Gloas spec." required: [aggregation_bits, data, signature] properties: aggregation_bits: @@ -31,7 +31,7 @@ Gloas: PayloadAttestationMessage: type: object - description: "The [`PayloadAttestationMessage`](https://github.com/ethereum/consensus-specs/blob/00d531949b1f30516979b60ddd2a411e7f388299/specs/gloas/beacon-chain.md#payloadattestationmessage) object from the CL Gloas spec." + description: "The [`PayloadAttestationMessage`](https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.2/specs/gloas/beacon-chain.md#payloadattestationmessage) object from the CL Gloas spec." required: [validator_index, data, signature] properties: validator_index: diff --git a/validator-flow.md b/validator-flow.md index 7c006f3c..b36c0714 100644 --- a/validator-flow.md +++ b/validator-flow.md @@ -24,7 +24,6 @@ If proposing block, then at immediate start of slot: Monitor chain block reorganization events (TBD) as they could change block proposers. If reorg is detected, ask for new proposer duties and proceed from 1. - ### Attestation On start of every epoch, validator should ask for attester duties for epoch + 1. @@ -40,14 +39,14 @@ Attesting: set `is_aggregator` to `True`, 2. Wait for new BeaconBlock for the assigned slot (either stream updates or poll) - Pre-Gloas forks: Max wait `SECONDS_PER_SLOT / 3` seconds into the assigned slot - - Post-Gloas forks: Max wait [ATTESTATION_DUE_BPS_GLOAS](https://github.com/ethereum/consensus-specs/blob/00d531949b1f30516979b60ddd2a411e7f388299/specs/gloas/validator.md#time-parameters) seconds into the assigned slot + - Post-Gloas forks: Max wait [ATTESTATION_DUE_BPS_GLOAS](https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.2/specs/gloas/validator.md#time-parameters) seconds into the assigned slot 3. [Fetch AttestationData](#/ValidatorRequiredApi/produceAttestationData) 4. [Submit Attestation](#/ValidatorRequiredApi/submitPoolAttestations) (AttestationData + aggregation bits) - Aggregation bits are `Bitlist` with length of committee (received in AttesterDuty) with bit on position `validator_committee_index` (see AttesterDuty) set to true 5. If aggregator: - Pre-Gloas forks: Wait for `SECONDS_PER_SLOT * 2 / 3` seconds into the assigned slot - - Post-Gloas forks: Wait for [AGGREGATE_DUE_BPS_GLOAS](https://github.com/ethereum/consensus-specs/blob/00d531949b1f30516979b60ddd2a411e7f388299/specs/gloas/validator.md#time-parameters) seconds into the assigned slot + - Post-Gloas forks: Wait for [AGGREGATE_DUE_BPS_GLOAS](https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.2/specs/gloas/validator.md#time-parameters) seconds into the assigned slot - [Fetch aggregated Attestation](#/ValidatorRequiredApi/getAggregatedAttestation) from Beacon Node you've subscribed to your subnet - [Publish SignedAggregateAndProofs](#/ValidatorRequiredApi/publishAggregateAndProofs) @@ -61,7 +60,7 @@ Result are array of objects with validator index and assigned slot for payload t PTC Attesting: 1. Wait for execution payload and blobs to become available for the assigned slot (either stream updates or poll) - - Max wait [PAYLOAD_ATTESTATION_DUE_BPS](https://github.com/ethereum/consensus-specs/blob/00d531949b1f30516979b60ddd2a411e7f388299/specs/gloas/validator.md#time-parameters) seconds into the assigned slot + - Max wait [PAYLOAD_ATTESTATION_DUE_BPS](https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.2/specs/gloas/validator.md#time-parameters) seconds into the assigned slot 2. [Fetch PayloadAttestationData](#/ValidatorRequiredApi/producePayloadAttestationData) for the assigned slot 3. Sign PayloadAttestationData to create PayloadAttestationMessage 4. [Submit PayloadAttestationMessages](#/ValidatorRequiredApi/submitPayloadAttestationMessages) @@ -79,7 +78,7 @@ in the beacon state's builder registry. Building: 1. [Fetch ExecutionPayloadBid](#/Validator/getExecutionPayloadBid) from beacon node for the current or next slot's proposer to include. - Beacon node obtains payload via `engine_getPayload` call to execution client -2. Cache fields required to form an [ExecutionPayloadEnvelope](https://github.com/ethereum/consensus-specs/blob/00d531949b1f30516979b60ddd2a411e7f388299/specs/gloas/beacon-chain.md#executionpayloadenvelope) +2. Cache fields required to form an [ExecutionPayloadEnvelope](https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.2/specs/gloas/beacon-chain.md#executionpayloadenvelope) 2. Sign ExecutionPayloadBid to create SignedExecutionPayloadBid 3. [Submit SignedExecutionPayloadBid](#/Beacon/publishExecutionPayloadBid) to network for proposer consideration 4. TODO: Envelope fetching and publishing flow (stateless vs. stateful) to be detailed in separate PR From 1679d4a8e00b811bd19d117bff4991929ea1b611 Mon Sep 17 00:00:00 2001 From: Nico Flaig Date: Wed, 11 Feb 2026 12:36:56 +0000 Subject: [PATCH 38/42] Add missing changelog entries --- CHANGES.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/CHANGES.md b/CHANGES.md index 92b199cb..b421091f 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -9,12 +9,17 @@ 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) | |---------------------------------------------------------------------------------------------------------------------|--------------------------------------------------|---------------------------------------------------|----------------------------------------------------|-------------------------------------------------|-------------------------------------------| | [#552](https://github.com/ethereum/beacon-APIs/pull/552) `GET /eth/v1/validator/execution_payload_bid/{slot}/{builder_index}` added | | | | | | -| [#552](https://github.com/ethereum/beacon-APIs/pull/552) `GET /eth/v1/validator/payload_attestation_data` added | | | | | | +| [#552](https://github.com/ethereum/beacon-APIs/pull/552) `GET /eth/v1/validator/payload_attestation_data/{slot}` added | | | | | | | [#552](https://github.com/ethereum/beacon-APIs/pull/552) `POST /eth/v1/validator/duties/ptc/{epoch}` added | | | | | | | [#552](https://github.com/ethereum/beacon-APIs/pull/552) `POST /eth/v1/beacon/execution_payload_bid` added | | | | | | | [#552](https://github.com/ethereum/beacon-APIs/pull/552) `GET /eth/v1/beacon/execution_payload_envelope/{block_id}` added | | | | | | +| [#552](https://github.com/ethereum/beacon-APIs/pull/552) `GET /eth/v1/beacon/pool/payload_attestations` added | | | | | | | [#552](https://github.com/ethereum/beacon-APIs/pull/552) `POST /eth/v1/beacon/pool/payload_attestations` added | | | | | | +| [#552](https://github.com/ethereum/beacon-APIs/pull/552) `GET /eth/v2/beacon/blocks/{block_id}` updated | | | | | | | [#552](https://github.com/ethereum/beacon-APIs/pull/552) `POST /eth/v2/beacon/blocks` updated | | | | | | +| [#552](https://github.com/ethereum/beacon-APIs/pull/552) `execution_payload_available EVENT` added | | | | | | +| [#552](https://github.com/ethereum/beacon-APIs/pull/552) `execution_payload_bid EVENT` added | | | | | | +| [#552](https://github.com/ethereum/beacon-APIs/pull/552) `payload_attestation_message EVENT` added | | | | | | | [#563](https://github.com/ethereum/beacon-APIs/pull/563) `GET /eth/v2/validator/duties/proposer/{epoch}` added | | | | | | | [#563](https://github.com/ethereum/beacon-APIs/pull/563) `GET /eth/v1/validator/duties/proposer/{epoch}` deprecated | | | | | | | [#568](https://github.com/ethereum/beacon-APIs/pull/568) `GET /eth/v2/node/version` added | | | | | | From 841f6032db1186ac65e326d46fa344ff05a7a1b4 Mon Sep 17 00:00:00 2001 From: Nico Flaig Date: Wed, 11 Feb 2026 12:39:47 +0000 Subject: [PATCH 39/42] Keep phase0 spec references as before --- types/gloas/block.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/types/gloas/block.yaml b/types/gloas/block.yaml index 6a026db5..f869bc7e 100644 --- a/types/gloas/block.yaml +++ b/types/gloas/block.yaml @@ -48,7 +48,7 @@ Gloas: maxItems: 4 BeaconBlock: - description: "The [`BeaconBlock`](https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.2/specs/phase0/beacon-chain.md#beaconblock) object from the CL Gloas spec." + description: "The [`BeaconBlock`](https://github.com/ethereum/consensus-specs/blob/v1.5.0/specs/phase0/beacon-chain.md#beaconblock) object from the CL Gloas spec." allOf: - $ref: "../altair/block.yaml#/Altair/BeaconBlockCommon" - type: object @@ -59,7 +59,7 @@ Gloas: SignedBeaconBlock: type: object - description: "The [`SignedBeaconBlock`](https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.2/specs/phase0/beacon-chain.md#signedbeaconblock) object envelope from the CL Gloas spec." + description: "The [`SignedBeaconBlock`](https://github.com/ethereum/consensus-specs/blob/v1.5.0/specs/phase0/beacon-chain.md#signedbeaconblock) object envelope from the CL Gloas spec." required: [message, signature] properties: message: From cbc7a43d288d596335268fadaceeb0a9fe4ff08d Mon Sep 17 00:00:00 2001 From: Nico Flaig Date: Wed, 11 Feb 2026 12:42:55 +0000 Subject: [PATCH 40/42] Fix spellcheck --- wordlist.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/wordlist.txt b/wordlist.txt index ddfb86d1..6d758d1e 100644 --- a/wordlist.txt +++ b/wordlist.txt @@ -44,3 +44,4 @@ PTC ptc PtcDuty produceBlockV +stateful From 7c50bdca3cbf18a9b4ec87d6f3f831d77ae1e295 Mon Sep 17 00:00:00 2001 From: Nico Flaig Date: Wed, 11 Feb 2026 12:52:37 +0000 Subject: [PATCH 41/42] Final touch --- apis/beacon/pool/payload_attestations.yaml | 2 +- types/gloas/payload_attestation.yaml | 4 ++-- validator-flow.md | 6 ++---- 3 files changed, 5 insertions(+), 7 deletions(-) diff --git a/apis/beacon/pool/payload_attestations.yaml b/apis/beacon/pool/payload_attestations.yaml index 873fdb03..15318cb5 100644 --- a/apis/beacon/pool/payload_attestations.yaml +++ b/apis/beacon/pool/payload_attestations.yaml @@ -70,7 +70,7 @@ post: - Beacon - ValidatorRequiredApi requestBody: - description: "Array of PayloadAttestationMessage objects to be submitted." + description: "Array of `PayloadAttestationMessage` objects to be submitted." required: true content: application/json: diff --git a/types/gloas/payload_attestation.yaml b/types/gloas/payload_attestation.yaml index aa88697a..81b18273 100644 --- a/types/gloas/payload_attestation.yaml +++ b/types/gloas/payload_attestation.yaml @@ -6,13 +6,13 @@ Gloas: properties: beacon_block_root: $ref: "../primitive.yaml#/Root" - description: "Hash tree root of the beacon block associated with this ptc attestation" + description: "Hash tree root of the beacon block associated with this PTC attestation" slot: $ref: "../primitive.yaml#/Uint64" description: "The slot for which the payload attestation is being made" payload_present: type: boolean - description: "True if a SignedExecutionPayloadEnvelope has been seen referencing this block" + description: "True if a `SignedExecutionPayloadEnvelope` has been seen referencing this block" blob_data_available: type: boolean description: "True if blob data is available for this block" diff --git a/validator-flow.md b/validator-flow.md index b36c0714..95214c90 100644 --- a/validator-flow.md +++ b/validator-flow.md @@ -62,7 +62,7 @@ PTC Attesting: 1. Wait for execution payload and blobs to become available for the assigned slot (either stream updates or poll) - Max wait [PAYLOAD_ATTESTATION_DUE_BPS](https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.2/specs/gloas/validator.md#time-parameters) seconds into the assigned slot 2. [Fetch PayloadAttestationData](#/ValidatorRequiredApi/producePayloadAttestationData) for the assigned slot -3. Sign PayloadAttestationData to create PayloadAttestationMessage +3. Sign `PayloadAttestationData` to create `PayloadAttestationMessage` 4. [Submit PayloadAttestationMessages](#/ValidatorRequiredApi/submitPayloadAttestationMessages) - Attestation indicates whether execution payload envelope has been seen for the block and if blobs were received @@ -79,10 +79,8 @@ Building: 1. [Fetch ExecutionPayloadBid](#/Validator/getExecutionPayloadBid) from beacon node for the current or next slot's proposer to include. - Beacon node obtains payload via `engine_getPayload` call to execution client 2. Cache fields required to form an [ExecutionPayloadEnvelope](https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.2/specs/gloas/beacon-chain.md#executionpayloadenvelope) -2. Sign ExecutionPayloadBid to create SignedExecutionPayloadBid +2. Sign `ExecutionPayloadBid` to create `SignedExecutionPayloadBid` 3. [Submit SignedExecutionPayloadBid](#/Beacon/publishExecutionPayloadBid) to network for proposer consideration 4. TODO: Envelope fetching and publishing flow (stateless vs. stateful) to be detailed in separate PR Monitor for block proposals containing your bid to trigger envelope release. - - From d5036b8ec278aa0c651712685457de722eddc179 Mon Sep 17 00:00:00 2001 From: Nico Flaig Date: Thu, 12 Feb 2026 09:32:24 +0000 Subject: [PATCH 42/42] Apply suggestion from hangleang --- apis/beacon/execution_payload/envelope_get.yaml | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/apis/beacon/execution_payload/envelope_get.yaml b/apis/beacon/execution_payload/envelope_get.yaml index 1838847c..677964c3 100644 --- a/apis/beacon/execution_payload/envelope_get.yaml +++ b/apis/beacon/execution_payload/envelope_get.yaml @@ -7,7 +7,10 @@ get: tags: - Beacon parameters: - - $ref: '../../../beacon-node-oapi.yaml#/components/parameters/BlockId' + - name: block_id + in: path + required: true + $ref: '../../../beacon-node-oapi.yaml#/components/parameters/BlockId' responses: "200": description: "Successful response"