diff --git a/CHANGES.md b/CHANGES.md index 76e976b6..b421091f 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -8,6 +8,18 @@ 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/{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 | | | | | | 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/blocks/blocks.v2.yaml b/apis/beacon/blocks/blocks.v2.yaml index 7019e0d5..b93e6db9 100644 --- a/apis/beacon/blocks/blocks.v2.yaml +++ b/apis/beacon/blocks/blocks.v2.yaml @@ -11,9 +11,10 @@ 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 - the beacon node to broadcast all given blobs. The broadcast behaviour may be adjusted via the - `broadcast_validation` query parameter. + successfully broadcast but failed integration. For Deneb/Electra/Fulu, this additionally instructs + 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 @@ -49,6 +50,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/beacon/execution_payload/bid.yaml b/apis/beacon/execution_payload/bid.yaml new file mode 100644 index 00000000..8e26b5c4 --- /dev/null +++ b/apis/beacon/execution_payload/bid.yaml @@ -0,0 +1,42 @@ +post: + operationId: publishExecutionPayloadBid + summary: Publish signed execution payload bid + description: | + 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 + 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 + 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." + "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" + "415": + $ref: "../../../beacon-node-oapi.yaml#/components/responses/UnsupportedMediaType" + "500": + $ref: "../../../beacon-node-oapi.yaml#/components/responses/InternalError" diff --git a/apis/beacon/execution_payload/envelope_get.yaml b/apis/beacon/execution_payload/envelope_get.yaml new file mode 100644 index 00000000..677964c3 --- /dev/null +++ b/apis/beacon/execution_payload/envelope_get.yaml @@ -0,0 +1,61 @@ +get: + operationId: getSignedExecutionPayloadEnvelope + summary: Get signed execution payload envelope + description: | + 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 + parameters: + - name: block_id + in: path + required: true + $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 `SignedExecutionPayloadEnvelope` 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/pool/payload_attestations.yaml b/apis/beacon/pool/payload_attestations.yaml new file mode 100644 index 00000000..15318cb5 --- /dev/null +++ b/apis/beacon/pool/payload_attestations.yaml @@ -0,0 +1,96 @@ +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 + headers: + Eth-Consensus-Version: + $ref: '../../../beacon-node-oapi.yaml#/components/headers/Eth-Consensus-Version' + 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.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: + 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: submitPayloadAttestationMessages + summary: Submit payload attestation messages + description: | + Submits payload attestation messages to the beacon node. + + 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: + $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 + requestBody: + description: "Array of `PayloadAttestationMessage` objects to be submitted." + required: true + content: + application/json: + schema: + type: array + items: + $ref: "../../../beacon-node-oapi.yaml#/components/schemas/Gloas.PayloadAttestationMessage" + application/octet-stream: + schema: + 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" + "400": + description: "Errors with one or more payload attestation messages" + content: + application/json: + schema: + $ref: "../../../beacon-node-oapi.yaml#/components/schemas/IndexedErrorMessage" + "415": + $ref: "../../../beacon-node-oapi.yaml#/components/responses/UnsupportedMediaType" + "500": + $ref: "../../../beacon-node-oapi.yaml#/components/responses/InternalError" diff --git a/apis/eventstream/index.yaml b/apis/eventstream/index.yaml index 3ed6dc86..8f8d2298 100644 --- a/apis/eventstream/index.yaml +++ b/apis/eventstream/index.yaml @@ -39,6 +39,9 @@ get: - payload_attributes - blob_sidecar - data_column_sidecar + - execution_payload_available + - execution_payload_bid + - payload_attestation_message responses: "200": description: Opened SSE stream. @@ -158,6 +161,21 @@ 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"} + 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: {"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: | + 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/apis/validator/block.v3.yaml b/apis/validator/block.v3.yaml index 18923ee9..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 - will be added to as forks progress. + are for all pre-Gloas forks. This endpoint is not forwards compatible after the Gloas fork. parameters: - name: slot in: path diff --git a/apis/validator/duties/ptc.yaml b/apis/validator/duties/ptc.yaml new file mode 100644 index 00000000..c8691f59 --- /dev/null +++ b/apis/validator/duties/ptc.yaml @@ -0,0 +1,72 @@ +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, + 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/apis/validator/execution_payload_bid.yaml b/apis/validator/execution_payload_bid.yaml new file mode 100644 index 00000000..3dee04da --- /dev/null +++ b/apis/validator/execution_payload_bid.yaml @@ -0,0 +1,70 @@ +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" + content: + application/json: + schema: + title: GetExecutionPayloadBidResponse + type: object + required: [version, data] + properties: + version: + type: string + enum: [gloas] + example: "gloas" + data: + $ref: "../../beacon-node-oapi.yaml#/components/schemas/Gloas.ExecutionPayloadBid" + application/octet-stream: + schema: + description: "SSZ serialized `ExecutionPayloadBid` bytes. Use Accept header to choose this response type" + "400": + description: "Invalid request - the slot or builder_index is invalid" + content: + application/json: + schema: + $ref: "../../beacon-node-oapi.yaml#/components/schemas/ErrorMessage" + 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" + "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/apis/validator/payload_attestation_data.yaml b/apis/validator/payload_attestation_data.yaml new file mode 100644 index 00000000..5aa3fee3 --- /dev/null +++ b/apis/validator/payload_attestation_data.yaml @@ -0,0 +1,50 @@ +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: path + 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" + headers: + Eth-Consensus-Version: + $ref: "../../beacon-node-oapi.yaml#/components/headers/Eth-Consensus-Version" + content: + application/json: + schema: + title: ProducePayloadAttestationDataResponse + type: object + required: [version, data] + properties: + version: + type: string + enum: [gloas] + example: "gloas" + 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 57389404..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 @@ -104,6 +104,10 @@ 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/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: @@ -134,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: @@ -184,10 +190,14 @@ paths: $ref: "./apis/validator/duties/proposer.v2.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: $ref: "./apis/validator/attestation_data.yaml" + /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" /eth/v2/validator/aggregate_and_proofs: @@ -210,6 +220,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" @@ -233,6 +245,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: @@ -339,8 +353,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: @@ -433,6 +447,24 @@ 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" + Gloas.ExecutionPayloadBid: + $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" + 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: @@ -479,7 +511,7 @@ 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: 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." diff --git a/types/gloas/block.yaml b/types/gloas/block.yaml new file mode 100644 index 00000000..f869bc7e --- /dev/null +++ b/types/gloas/block.yaml @@ -0,0 +1,68 @@ +Gloas: + BeaconBlockBody: + type: object + 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: + $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" + 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." + 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..e8818060 --- /dev/null +++ b/types/gloas/execution_payload_bid.yaml @@ -0,0 +1,40 @@ +Gloas: + ExecutionPayloadBid: + type: object + 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: + $ref: "../primitive.yaml#/Root" + parent_block_root: + $ref: "../primitive.yaml#/Root" + block_hash: + $ref: "../primitive.yaml#/Root" + prev_randao: + $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" + execution_payment: + $ref: "../primitive.yaml#/Gwei" + blob_kzg_commitments: + type: array + items: + $ref: '../primitive.yaml#/KZGCommitment' + + SignedExecutionPayloadBid: + type: object + 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: + $ref: "#/Gloas/ExecutionPayloadBid" + signature: + $ref: "../primitive.yaml#/Signature" diff --git a/types/gloas/execution_payload_envelope.yaml b/types/gloas/execution_payload_envelope.yaml new file mode 100644 index 00000000..2f8e6c32 --- /dev/null +++ b/types/gloas/execution_payload_envelope.yaml @@ -0,0 +1,33 @@ +Gloas: + ExecutionPayloadEnvelope: + type: object + 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: + $ref: "../deneb/execution_payload.yaml#/Deneb/ExecutionPayload" + execution_requests: + $ref: "../electra/execution_requests.yaml#/Electra/ExecutionRequests" + builder_index: + $ref: "../primitive.yaml#/Uint64" + description: "Index of the builder that created this execution payload" + beacon_block_root: + $ref: "../primitive.yaml#/Root" + description: "Root of the beacon block for this payload" + slot: + $ref: "../primitive.yaml#/Uint64" + description: "Slot number for this execution payload" + state_root: + $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/v1.7.0-alpha.2/specs/gloas/beacon-chain.md#signedexecutionpayloadenvelope) object from the CL Gloas spec." + required: [message, signature] + properties: + message: + $ref: "#/Gloas/ExecutionPayloadEnvelope" + signature: + $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 new file mode 100644 index 00000000..81b18273 --- /dev/null +++ b/types/gloas/payload_attestation.yaml @@ -0,0 +1,44 @@ +Gloas: + PayloadAttestationData: + type: object + 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: + $ref: "../primitive.yaml#/Root" + 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" + 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/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: + $ref: "../primitive.yaml#/Bitvector" + data: + $ref: "#/Gloas/PayloadAttestationData" + signature: + $ref: "../primitive.yaml#/Signature" + + PayloadAttestationMessage: + type: object + 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: + $ref: "../primitive.yaml#/Uint64" + description: "Index of the validator submitting the payload attestation" + data: + $ref: "#/Gloas/PayloadAttestationData" + signature: + $ref: "../primitive.yaml#/Signature" + description: "BLS signature of the payload attestation data" diff --git a/validator-flow.md b/validator-flow.md index 37120fed..95214c90 100644 --- a/validator-flow.md +++ b/validator-flow.md @@ -15,9 +15,11 @@ 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: [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. 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. @@ -36,15 +38,49 @@ 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 + - 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/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: - - Wait for `SECONDS_PER_SLOT * 2 / 3` 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 [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) 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 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: +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` +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. +If reorg is detected, ask for new PTC duties and proceed from 1.. + +### Builder (Optional) + +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. + - 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` +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. diff --git a/wordlist.txt b/wordlist.txt index 84183ba8..6d758d1e 100644 --- a/wordlist.txt +++ b/wordlist.txt @@ -40,3 +40,8 @@ fulu gloas LH ClientVersionV +PTC +ptc +PtcDuty +produceBlockV +stateful