diff --git a/CHANGES.md b/CHANGES.md index 0ba141e2..5ece0aaf 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -33,6 +33,11 @@ There are likely to be descriptions etc outside of the list below, but new query | [#590](https://github.com/ethereum/beacon-APIs/pull/590) `head_v2 EVENT` added | | | | | | | [#590](https://github.com/ethereum/beacon-APIs/pull/590) `head EVENT` deprecated | | | | | | | [#598](https://github.com/ethereum/beacon-APIs/pull/598) `fast_confirmation EVENT` added | | | | | | +| [#608](https://github.com/ethereum/beacon-APIs/pull/608) `POST /eth/v1/validator/proposer_preferences` added | | | | | | +| [#608](https://github.com/ethereum/beacon-APIs/pull/608) `proposer_preferences EVENT` added | | | | | | +| [#608](https://github.com/ethereum/beacon-APIs/pull/608) `POST /eth/v1/validator/prepare_beacon_proposer` deprecated | | | | | | +| [#608](https://github.com/ethereum/beacon-APIs/pull/608) `POST /eth/v1/validator/register_validator` deprecated | | | | | | +| [#608](https://github.com/ethereum/beacon-APIs/pull/608) `POST /eth/v1/validator/beacon_committee_subscriptions` updated | | | | | | The Following are no longer in the Standard API, removed since the latest version. diff --git a/apis/eventstream/index.yaml b/apis/eventstream/index.yaml index 3b2fa0af..1373747d 100644 --- a/apis/eventstream/index.yaml +++ b/apis/eventstream/index.yaml @@ -45,6 +45,7 @@ get: - execution_payload_bid - payload_attestation_message - fast_confirmation + - proposer_preferences responses: "200": description: Opened SSE stream. @@ -194,6 +195,11 @@ get: value: | event: fast_confirmation data: {"block": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", "slot": "1", "current_slot": "2"} + proposer_preferences: + description: The node has received a `SignedProposerPreferences` (from P2P or API) that passes gossip validation on the `proposer_preferences` topic + value: | + event: proposer_preferences + data: {"version":"gloas", "data":{"message": {"dependent_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", "proposal_slot": "32", "validator_index": "123", "fee_recipient": "0x0000000000000000000000000000000000000000", "target_gas_limit": "60000000"}, "signature": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505"}} "400": description: "The topics supplied could not be parsed" content: diff --git a/apis/validator/beacon_committee_subscriptions.yaml b/apis/validator/beacon_committee_subscriptions.yaml index 1e3a0e0f..2f313d25 100644 --- a/apis/validator/beacon_committee_subscriptions.yaml +++ b/apis/validator/beacon_committee_subscriptions.yaml @@ -8,6 +8,13 @@ post: If validator `is_aggregator`, beacon node must: - announce subnet topic subscription on gossipsub - aggregate attestations received on that subnet + + Beacon nodes SHOULD use the set of validators that have submitted subscriptions via this + endpoint to determine which validators are using the node for duties and to calculate the + node's required custody group count (CGC). Validator clients SHOULD submit one entry per + attached active validator per attestation duty, including when multiple validators share + the same `(slot, committee_index)`, so the beacon node tracks every attached validator + rather than only one per subnet. tags: - ValidatorRequiredApi - Validator diff --git a/apis/validator/prepare_beacon_proposer.yaml b/apis/validator/prepare_beacon_proposer.yaml index 59c2ca19..8218377f 100644 --- a/apis/validator/prepare_beacon_proposer.yaml +++ b/apis/validator/prepare_beacon_proposer.yaml @@ -1,7 +1,13 @@ post: operationId: "prepareBeaconProposer" summary: Provide beacon node with proposals for the given validators. + deprecated: true description: | + Deprecated from Gloas onwards in favor of + `POST /eth/v1/validator/proposer_preferences`, which supersedes both fee recipient and + gas limit preferences. Beacon node support for this endpoint pre-Gloas is REQUIRED; + post-Gloas support is OPTIONAL and the endpoint MAY be removed. + Prepares the beacon node for potential proposers by supplying information required when proposing blocks for the given validators. The information supplied for each validator index will persist through the epoch in which diff --git a/apis/validator/proposer_preferences.yaml b/apis/validator/proposer_preferences.yaml new file mode 100644 index 00000000..565d8633 --- /dev/null +++ b/apis/validator/proposer_preferences.yaml @@ -0,0 +1,58 @@ +post: + operationId: submitProposerPreferences + summary: Submit signed proposer preferences + description: | + Verifies given signed proposer preferences and publishes them on the `proposer_preferences` + gossipsub topic. + + Notes: + - Validator clients SHOULD begin submitting signed proposer preferences one epoch before the + Gloas fork activates, so the proposer preference caches kept by both beacon nodes and + builders are warm at the fork boundary, letting builders prepare valid bids for the first + Gloas slots. + - Until the Gloas fork activates, beacon nodes MUST continue to honor fee recipient and gas + limit information supplied via `POST /eth/v1/validator/prepare_beacon_proposer` and + `POST /eth/v1/validator/register_validator`. From the Gloas fork onwards, signed proposer + preferences supersede both endpoints as the source of proposer fee recipient and gas + limit preferences. + - For validators served by the beacon node, if no signed proposer preferences are available + for a given proposal slot, the beacon node SHOULD fall back to the parent block's gas limit + when preparing the local payload or accepting bids for that validator. On the p2p network, + bids whose fee recipient or gas limit do not match a validator's preferences are rejected at + gossip validation, while bids for a slot with no available preferences are ignored; applying + sensible defaults reduces missed proposals during the transition. + 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 signed proposer preferences being submitted belongs." + tags: + - Validator + - ValidatorRequiredApi + requestBody: + description: "Array of `SignedProposerPreferences` objects to be submitted." + required: true + content: + application/json: + schema: + type: array + items: + $ref: "../../beacon-node-oapi.yaml#/components/schemas/Gloas.SignedProposerPreferences" + application/octet-stream: + schema: + description: "SSZ serialized `List[SignedProposerPreferences, (MIN_SEED_LOOKAHEAD + 1) * SLOTS_PER_EPOCH]` bytes. Use Content-Type header to indicate that SSZ data is contained in the request body." + responses: + "200": + description: "Signed proposer preferences are stored in pool and broadcasted to the network" + "400": + description: "Errors with one or more signed proposer preferences" + 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/validator/register_validator.yaml b/apis/validator/register_validator.yaml index e7682dc2..32754854 100644 --- a/apis/validator/register_validator.yaml +++ b/apis/validator/register_validator.yaml @@ -1,7 +1,13 @@ post: operationId: "registerValidator" summary: Provide beacon node with registrations for the given validators to the external builder network. + deprecated: true description: | + Deprecated from Gloas onwards. Under Gloas, proposer fee recipient and gas limit preferences + are expressed via `POST /eth/v1/validator/proposer_preferences` instead. Beacon node support + for this endpoint pre-Gloas is REQUIRED; post-Gloas support is OPTIONAL and the endpoint + MAY be removed. + Prepares the beacon node for engaging with external builders. The information must be sent by the beacon node to the builder network. It is expected that the validator client will send this information periodically diff --git a/beacon-node-oapi.yaml b/beacon-node-oapi.yaml index 89af15d9..859e2eb1 100644 --- a/beacon-node-oapi.yaml +++ b/beacon-node-oapi.yaml @@ -222,6 +222,8 @@ paths: $ref: "./apis/validator/prepare_beacon_proposer.yaml" /eth/v1/validator/register_validator: $ref: "./apis/validator/register_validator.yaml" + /eth/v1/validator/proposer_preferences: + $ref: "./apis/validator/proposer_preferences.yaml" /eth/v1/validator/liveness/{epoch}: $ref: "./apis/validator/liveness.yaml" /eth/v1/validator/execution_payload_bids/{slot}/{builder_index}: @@ -483,6 +485,10 @@ components: $ref: "./types/gloas/payload_attestation.yaml#/Gloas/PayloadAttestation" Gloas.PayloadAttestationMessage: $ref: "./types/gloas/payload_attestation.yaml#/Gloas/PayloadAttestationMessage" + Gloas.ProposerPreferences: + $ref: "./types/gloas/proposer_preferences.yaml#/Gloas/ProposerPreferences" + Gloas.SignedProposerPreferences: + $ref: "./types/gloas/proposer_preferences.yaml#/Gloas/SignedProposerPreferences" Fulu.BlockContents: $ref: "./types/fulu/block_contents.yaml#/Fulu/BlockContents" Fulu.SignedBlockContents: diff --git a/types/gloas/proposer_preferences.yaml b/types/gloas/proposer_preferences.yaml new file mode 100644 index 00000000..2fd0881d --- /dev/null +++ b/types/gloas/proposer_preferences.yaml @@ -0,0 +1,31 @@ +Gloas: + ProposerPreferences: + type: object + description: "The [`ProposerPreferences`](https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.11/specs/gloas/p2p-interface.md#new-proposerpreferences) object from the CL Gloas spec." + required: [dependent_root, proposal_slot, validator_index, fee_recipient, target_gas_limit] + properties: + dependent_root: + $ref: "../primitive.yaml#/Root" + description: "Shuffling dependent root for the epoch of `proposal_slot`, based on the validator's head." + proposal_slot: + $ref: "../primitive.yaml#/Uint64" + description: "Slot for which the validator is the proposer." + validator_index: + $ref: "../primitive.yaml#/Uint64" + description: "Index of the proposing validator." + fee_recipient: + $ref: "../primitive.yaml#/ExecutionAddress" + description: "Address to receive the builder payment." + target_gas_limit: + $ref: "../primitive.yaml#/Uint64" + description: "Preferred gas limit for the execution payload." + + SignedProposerPreferences: + type: object + description: "The [`SignedProposerPreferences`](https://github.com/ethereum/consensus-specs/blob/v1.7.0-alpha.11/specs/gloas/p2p-interface.md#new-signedproposerpreferences) object from the CL Gloas spec." + required: [message, signature] + properties: + message: + $ref: "#/Gloas/ProposerPreferences" + signature: + $ref: "../primitive.yaml#/Signature" diff --git a/wordlist.txt b/wordlist.txt index b2ab8513..b03ee999 100644 --- a/wordlist.txt +++ b/wordlist.txt @@ -45,4 +45,5 @@ ptc PtcDuty produceBlockV stateful +CGC RLP