From 108698205d2dfb0a6b65e025594f9e1a98f2b34a Mon Sep 17 00:00:00 2001 From: Jim McDonald Date: Sun, 14 Nov 2021 14:40:51 +0000 Subject: [PATCH 1/4] Addition of prepare_beacon_proposer endpoint. --- apis/validator/prepare_beacon_proposer.yaml | 40 +++++++++++++++++++++ beacon-node-oapi.yaml | 6 +++- types/primitive.yaml | 6 ++++ 3 files changed, 51 insertions(+), 1 deletion(-) create mode 100644 apis/validator/prepare_beacon_proposer.yaml diff --git a/apis/validator/prepare_beacon_proposer.yaml b/apis/validator/prepare_beacon_proposer.yaml new file mode 100644 index 00000000..b566f849 --- /dev/null +++ b/apis/validator/prepare_beacon_proposer.yaml @@ -0,0 +1,40 @@ +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 is considered persistent until overwritten + by new information for the given validator index, or until the beacon node + restarts. + + Note that bacause the information is not persistent across beacon node restarts + it is recommended that either the beacon node is monitored for restarts or this + information is refreshed by resending this request periodically (for example, + each epoch). + + 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}$" From 4ef648540d633c1eea0374aece9879276c754f7a Mon Sep 17 00:00:00 2001 From: Jim McDonald Date: Sun, 14 Nov 2021 21:10:08 +0000 Subject: [PATCH 2/4] Fix spelling mistake. --- apis/validator/prepare_beacon_proposer.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apis/validator/prepare_beacon_proposer.yaml b/apis/validator/prepare_beacon_proposer.yaml index b566f849..ad2d17b9 100644 --- a/apis/validator/prepare_beacon_proposer.yaml +++ b/apis/validator/prepare_beacon_proposer.yaml @@ -8,7 +8,7 @@ post: by new information for the given validator index, or until the beacon node restarts. - Note that bacause the information is not persistent across beacon node restarts + Note that because the information is not persistent across beacon node restarts it is recommended that either the beacon node is monitored for restarts or this information is refreshed by resending this request periodically (for example, each epoch). From 684a91a90e7f90aba153428b10877032ea5370af Mon Sep 17 00:00:00 2001 From: Jim McDonald Date: Fri, 19 Nov 2021 12:42:07 +0000 Subject: [PATCH 3/4] Add note about checking fee recpient in proposal. --- apis/validator/prepare_beacon_proposer.yaml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/apis/validator/prepare_beacon_proposer.yaml b/apis/validator/prepare_beacon_proposer.yaml index ad2d17b9..41c17487 100644 --- a/apis/validator/prepare_beacon_proposer.yaml +++ b/apis/validator/prepare_beacon_proposer.yaml @@ -8,6 +8,11 @@ post: by new information for the given validator index, or until the beacon node restarts. + 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. + Note that because the information is not persistent across beacon node restarts it is recommended that either the beacon node is monitored for restarts or this information is refreshed by resending this request periodically (for example, From a3c9102db55882d4a20c83c69f9e12b094dd2253 Mon Sep 17 00:00:00 2001 From: Jim McDonald Date: Sat, 27 Nov 2021 20:07:06 +0000 Subject: [PATCH 4/4] Reword for change to transient retention of data. --- apis/validator/prepare_beacon_proposer.yaml | 21 +++++++++------------ 1 file changed, 9 insertions(+), 12 deletions(-) diff --git a/apis/validator/prepare_beacon_proposer.yaml b/apis/validator/prepare_beacon_proposer.yaml index 41c17487..e0985d19 100644 --- a/apis/validator/prepare_beacon_proposer.yaml +++ b/apis/validator/prepare_beacon_proposer.yaml @@ -4,19 +4,16 @@ post: 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 is considered persistent until overwritten - by new information for the given validator index, or until the beacon node - restarts. + 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. - 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. - - Note that because the information is not persistent across beacon node restarts - it is recommended that either the beacon node is monitored for restarts or this - information is refreshed by resending this request periodically (for example, - each epoch). + 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.