Merge pull request #178 from mcdee/potential-proposers

Addition of prepare_beacon_proposer endpoint.

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'

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"
+        example: "phase0"

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}$"