Fee Recipient API

apis/fee_recipient.yaml

@@ -0,0 +1,105 @@
+get:
+  operationId: ListFeeRecipients
+  summary: List Fee Recipient.
+  description: |
+    List the validator public key to eth address mappings for fee recipient feature as well as any default eth address mappings.
+    The beacon node may have its own default fee recipient not listed here.
+
+    WARNING: API only works POST MERGE(Bellatrix) 
+  security:
+    - bearerAuth: []
+  tags:
+    - Fee Recipient
+  responses:
+    "200":
+      description: Success response
+      content:
+        application/json:
+          schema:
+            title: ListFeeRecipientsResponse
+            type: object
+            required: [data]
+            properties:
+              data:
+                type: array
+                items:
+                  $ref: "../keymanager-oapi.yaml#/components/schemas/FeeRecipientMap"
+              default_fee_recipient_address:
+                $ref: "../keymanager-oapi.yaml#/components/schemas/Ethaddress"
+    "401":
+      $ref: "../keymanager-oapi.yaml#/components/responses/Unauthorized"
+    "403":
+      $ref: "../keymanager-oapi.yaml#/components/responses/Forbidden"
+    "500":
+      $ref: "../keymanager-oapi.yaml#/components/responses/InternalError"
+
+post:
+  operationId: SetFeeRecipient
+  summary: Set Fee Recipient.
+  description: |
+    Sets the validator client fee recipient mapping which will then update the beacon node.
+    Existing mappings for the same validator public key will be overwritten.
+    Specific Public keys not mapped will continue to use the default address for fee recipient in accordance to the startup of the validator client and beacon node.
+    Cannot specify default fee recipient address through API.
+
+    WARNING: API only works POST MERGE(Bellatrix) 
+  security:
+    - bearerAuth: []
+  tags:
+    - Fee Recipient
+  requestBody:
+    content:
+      application/json:
+        schema:
+          type: object
+          required: [pubkeys, ethaddresses]
+          properties:
+            pubkeys:
+              type: array
+              description: hexadecimal validator public keys.
+              items:
+                $ref: "../keymanager-oapi.yaml#/components/schemas/Pubkey"
+            ethaddresses:
+              type: array
+              description: hexadecimal eth addresses that the validator public key should be associated to, the length should match .
+              items:
+                $ref: "../keymanager-oapi.yaml#/components/schemas/Ethaddress"
+  responses:
+    "200":
+      description: Success response
+      content:
+        application/json:
+          schema:
+            title: SetFeeRecipientResponse
+            type: object
+            required: [data]
+            properties:
+              data:
+                type: array
+                description: Status result of each `request.pubkeys` with same length and order of `request.pubkeys`
+                items:
+                  type: object
+                  required: [status]
+                  properties:
+                    status:
+                      type: string
+                      description: |
+                        - set: new fee recipient mapping is set.
+                        - updated: existing fee recipient mapping is replaced.
+                        - error: Any other status different to the above: decrypting error, I/O errors, etc.
+                      enum:
+                        - set
+                        - updated
+                        - error
+                      example: set
+                    message:
+                      type: string
+                      description: error message if status == error
+    "400":
+      $ref: "../keymanager-oapi.yaml#/components/responses/BadRequest"
+    "401":
+      $ref: "../keymanager-oapi.yaml#/components/responses/Unauthorized"
+    "403":
+      $ref: "../keymanager-oapi.yaml#/components/responses/Forbidden"
+    "500":
+      $ref: "../keymanager-oapi.yaml#/components/responses/InternalError"

flows/client-specific/README.md

@@ -1,23 +1,24 @@
 # Prysm Specific Flows
 Prysm (https://github.com/prysmaticlabs/prysm) at the time of writing is one of the consensus layer clients implementing the Keymanager APIs.
+
 There are some Prysm specific quirks that this document would like to make users aware of.
 
 ### Prysm Default Validator API Address
 `http://127.0.0.1:7500/`
 
 Prysm by default runs on the above address when running with `--web` flag. please look at our documentation [here](https://docs.prylabs.network/docs/prysm-usage/web-interface) for more information. Prysm includes its own native UI implementation as well.
 
-
 ## prysm version 2.0.7
 
 1. Authentication: Prysm requires a bearer token for using the validator APIs, this token is also used for Prysm's native UI. For more information on where to find this token please look at the Prysm Docs.
 
-4. CORS: Prysm has CORS protection with ports 3000 (typically REACT), 7500, and 4200 (typically Angular). Please use the appropriate Prysm flag to enable other ports. Please look at the Prysm Docs for more information.
+2. CORS: Prysm has CORS protection with ports 3000 (typically REACT), 7500, and 4200 (typically Angular). Please use the appropriate Prysm flag to enable other ports. Please look at the Prysm Docs for more information.
 
 3. Prysm Wallet & keymanager Type: Prysm uses something called a Prysm wallet (not related to hardware wallet) to manage the validator keys inside the Prysm client. All users of Prysm must create a wallet with a specific keymanager type in order to import or delete validator keys. The following errors will be thrown if requirements are not met:
 - invalid wallet: either the wallet itself is corrupted, missing, or unable to be opened.
 - invalid keymanager type: the keymanager type when creating the wallet isn't usable with the keymanager APIs. Only the `local` keymanager type is allowed to be used for Keymanager APIs referring to the type where users are storing the validators in their local Prysm instance instead of using a remote signer.
 - validator service cannot get keymanager: The Keymanager API is called too soon after wallet creation.
+
 4. API middleware and Internal RPC: Prysm doesn't natively use REST and uses gRPC internally instead for APIs, that means Prysm is translating HTTP REST calls into RPC calls and vice versa. This can cause certain types of issues that although unintended, can happen.
 - Error code or error message unexpected: because our RPC codes are translated to HTTP errors there may be unexpected response codes in which case please report to the Prysm Team
-- Golang primitives default values: Golang (the programming language Prysm is written in) will default certain primatives by default (`string` as `""` instead of `null`, `boolean` as `false` instead of `null`, etc) we try to account for as many as we can with tests but please let the team know if Prysm behaves differently from other clients.
+- Golang primitives default values: Golang (the programming language Prysm is written in) will default certain primatives by default (`string` as `""` instead of `null`, `boolean` as `false` instead of `null`, etc) we try to account for as many as we can with tests but please let the team know if Prysm behaves differently from other clients.

keymanager-oapi.yaml

@@ -31,6 +31,8 @@ servers:
         default: "https://public-mainnet-node.ethereum.org"
 
 tags:
+  - name: Fee Recipient
+    description: Set of endpoints for management of fee recipient.
   - name: Local Key Manager
     description: Set of endpoints for key management of local keys.
   - name: Remote Key Manager
@@ -41,6 +43,8 @@ paths:
     $ref:  './apis/local_keystores.yaml'
   /eth/v1/remotekeys:
     $ref:  './apis/remote_keystores.yaml'
+  /eth/v1/feerecipient:
+    $ref:  './apis/fee_recipient.yaml'
 
 components:
   securitySchemes:
@@ -52,8 +56,12 @@ components:
   schemas:
     Pubkey:
       $ref: './types/public_key.yaml'
+    Ethaddress:
+      $ref: './types/eth_address.yaml'
     Keystore:
       $ref: './types/keystore.yaml'
+    FeeRecipientMap:
+      $ref: './types/fee_recipient_map.yaml'
     SignerDefinition:
       $ref: './types/signer_definition.yaml'
     ImportRemoteSignerDefinition:

types/eth_address.yaml

@@ -0,0 +1,4 @@
+type: string
+description: "An address on the execution (Ethereum 1) network."
+example: "0xabcf8e0d4e9587369b2301d0790347320302cc09"
+pattern: "^0x[a-fA-F0-9]{40}$"

types/fee_recipient_map.yaml

@@ -0,0 +1,7 @@
+type: object
+required: [pubkey,ethaddress]
+properties:
+  pubkey:
+    $ref: './public_key.yaml'
+  ethaddress:
+    $ref: './eth_address.yaml'