diff --git a/apis/validator/prepare_beacon_proposer.yaml b/apis/validator/prepare_beacon_proposer.yaml new file mode 100644 index 00000000..e0985d19 --- /dev/null +++ b/apis/validator/prepare_beacon_proposer.yaml @@ -0,0 +1,42 @@ +post: + operationId: "prepareBeaconProposer" + summary: Provide beacon node with proposals for the given validators. + description: | + 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 + the call is submitted and for a further two epochs after that, or until the + beacon node restarts. It is expected that validator clients will send this + information periodically, for example each epoch, to ensure beacon nodes have + correct and timely fee recipient information. + + Note that there is no guarantee that the beacon node will use the supplied fee + recipient when creating a block proposal, so on receipt of a proposed block the + validator should confirm that it finds the fee recipient within the block + acceptable before signing it. + + Also note that requests containing currently inactive or unknown validator + indices will be accepted, as they may become active at a later epoch. + tags: + - ValidatorRequiredApi + - Validator + requestBody: + content: + application/json: + schema: + type: array + items: + type: object + properties: + validator_index: + $ref: '../../beacon-node-oapi.yaml#/components/schemas/Uint64' + fee_recipient: + $ref: '../../beacon-node-oapi.yaml#/components/schemas/ExecutionAddress' + responses: + "200": + description: | + Preparation information has been received. + "400": + $ref: '../../beacon-node-oapi.yaml#/components/responses/InvalidRequest' + "500": + $ref: '../../beacon-node-oapi.yaml#/components/responses/InternalError' diff --git a/beacon-node-oapi.yaml b/beacon-node-oapi.yaml index 3de5d220..8451193b 100644 --- a/beacon-node-oapi.yaml +++ b/beacon-node-oapi.yaml @@ -142,6 +142,8 @@ paths: $ref: "./apis/validator/sync_committee_contribution.yaml" /eth/v1/validator/contribution_and_proofs: $ref: "./apis/validator/sync_committee_contribution_and_proof.yaml" + /eth/v1/validator/prepare_beacon_proposer: + $ref: "./apis/validator/prepare_beacon_proposer.yaml" /eth/v1/events: $ref: "./apis/eventstream/index.yaml" @@ -237,6 +239,8 @@ components: $ref: './types/altair/sync_committee.yaml#/Altair/SyncCommitteeContribution' Altair.SyncCommittee: $ref: './types/altair/sync_committee.yaml#/Altair/SyncCommitteeByValidatorIndices' + ExecutionAddress: + $ref: './types/primitive.yaml#/ExecutionAddress' parameters: StateId: @@ -258,4 +262,4 @@ components: schema: type: string enum: [phase0, altair] - example: "phase0" \ No newline at end of file + example: "phase0" diff --git a/types/primitive.yaml b/types/primitive.yaml index fe356e16..2943b2a9 100644 --- a/types/primitive.yaml +++ b/types/primitive.yaml @@ -58,3 +58,9 @@ Uint8: description: "Unsigned 8 bit integer, max value 255" pattern: "^[1-2]?[0-9]{1,2}$" example: "0" + +ExecutionAddress: + type: string + description: "An address on the execution (Ethereum 1) network." + example: "0xabcf8e0d4e9587369b2301d0790347320302cc09" + pattern: "^0x[a-fA-F0-9]{40}$"