From c294ea0f202a18b1545ad35aa23d82efcfa6e8bc Mon Sep 17 00:00:00 2001 From: Bharath Vedartham Date: Tue, 24 Mar 2026 22:59:38 +0530 Subject: [PATCH] add proposer preferences related apis --- apis/beacon/pool/proposer_preferences.yaml | 96 ++++++++++++++++++++++ apis/eventstream/index.yaml | 6 ++ beacon-node-oapi.yaml | 6 ++ types/gloas/proposer_preferences.yaml | 24 ++++++ 4 files changed, 132 insertions(+) create mode 100644 apis/beacon/pool/proposer_preferences.yaml create mode 100644 types/gloas/proposer_preferences.yaml diff --git a/apis/beacon/pool/proposer_preferences.yaml b/apis/beacon/pool/proposer_preferences.yaml new file mode 100644 index 00000000..08446d99 --- /dev/null +++ b/apis/beacon/pool/proposer_preferences.yaml @@ -0,0 +1,96 @@ +get: + operationId: getPoolProposerPreferences + summary: Get proposer preferences from operations pool + description: Retrieves proposer preferences 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: GetPoolProposerPreferencesResponse + 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.SignedProposerPreferences" + application/octet-stream: + schema: + description: "SSZ serialized `List[SignedProposerPreferences]` 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: submitSignedProposerPreferences + summary: Submit signed proposer preferences + description: | + Submits signed proposer preferences to the beacon node. + + The beacon node will validate each signed proposer preferences 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 signed proposer preferences passed validation and was + successfully stored and broadcast. + + If one or more signed proposer preferences 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 signed proposer preferences being submitted belongs." + tags: + - Beacon + - 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]` 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/eventstream/index.yaml b/apis/eventstream/index.yaml index edbe11bd..e37cbbc4 100644 --- a/apis/eventstream/index.yaml +++ b/apis/eventstream/index.yaml @@ -41,6 +41,7 @@ get: - execution_payload_available - execution_payload_bid - payload_attestation_message + - proposer_preferences responses: "200": description: Opened SSE stream. @@ -170,6 +171,11 @@ get: value: | event: payload_attestation_message data: {"version":"gloas", "data":{"validator_index": "123", "data": {"beacon_block_root": "0x9a2fefd2fdb57f74993c7780ea5b9030d2897b615b89f808011ca5aebed54eaf", "slot": "10", "payload_present": true, "blob_data_available": true}, "signature": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505"}} + 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": {"proposal_slot": "32", "validator_index": "123", "fee_recipient": "0x0000000000000000000000000000000000000000", "gas_limit": "30000000"}, "signature": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505"}} "400": description: "The topics supplied could not be parsed" content: diff --git a/beacon-node-oapi.yaml b/beacon-node-oapi.yaml index b30df420..e8109de9 100644 --- a/beacon-node-oapi.yaml +++ b/beacon-node-oapi.yaml @@ -138,6 +138,8 @@ paths: $ref: "./apis/beacon/pool/attestations.v2.yaml" /eth/v1/beacon/pool/payload_attestations: $ref: "./apis/beacon/pool/payload_attestations.yaml" + /eth/v1/beacon/pool/proposer_preferences: + $ref: "./apis/beacon/pool/proposer_preferences.yaml" /eth/v2/beacon/pool/attester_slashings: $ref: "./apis/beacon/pool/attester_slashings.v2.yaml" /eth/v1/beacon/pool/proposer_slashings: @@ -459,6 +461,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..f2e75fcf --- /dev/null +++ b/types/gloas/proposer_preferences.yaml @@ -0,0 +1,24 @@ +Gloas: + ProposerPreferences: + type: object + description: "The [`ProposerPreferences`](https://github.com/ethereum/consensus-specs/blob/master/specs/gloas/p2p-interface.md#proposerpreferences) object from the CL Gloas spec." + required: [proposal_slot, validator_index, fee_recipient, gas_limit] + properties: + proposal_slot: + $ref: "../primitive.yaml#/Uint64" + validator_index: + $ref: "../primitive.yaml#/Uint64" + fee_recipient: + $ref: "../primitive.yaml#/ExecutionAddress" + gas_limit: + $ref: "../primitive.yaml#/Uint64" + + SignedProposerPreferences: + type: object + description: "The [`SignedProposerPreferences`](https://github.com/ethereum/consensus-specs/blob/master/specs/gloas/p2p-interface.md#signedproposerpreferences) object from the CL Gloas spec." + required: [message, signature] + properties: + message: + $ref: "#/Gloas/ProposerPreferences" + signature: + $ref: "../primitive.yaml#/Signature"