Fee Recipient API

apis/fee_recipient.yaml

@@ -0,0 +1,84 @@
+get:
+  operationId: ListFeeRecipient
+  summary: List Fee Recipient.
+  description: |
+    List the validator public key to eth address mapping for fee recipient feature on a specific public key.
+    The validator public key will return with the default fee recipient address if a specific one was not found.
+
+    WARNING: The fee_recipient is not used on Phase0 or Altair networks.
+  security:
+    - bearerAuth: []
+  tags:
+    - Fee Recipient
+  parameters:
+      - in: path
+        name: pubkey
+        schema:
+          $ref: "../keymanager-oapi.yaml#/components/schemas/Pubkey"
+        required: true
+  responses:
+    "200":
+      description: Success response
+      content:
+        application/json:
+          schema:
+            title: ListFeeRecipientResponse
+            type: object
+            required: [data]
+            properties:
+              data:
+                $ref: "../keymanager-oapi.yaml#/components/schemas/FeeRecipient"
+    "401":
+      $ref: "../keymanager-oapi.yaml#/components/responses/Unauthorized"
+    "403":
+      $ref: "../keymanager-oapi.yaml#/components/responses/Forbidden"
+    "404":
+      $ref: "../keymanager-oapi.yaml#/components/responses/NotFound"
+    "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: The fee_recipient is not used on Phase0 or Altair networks.
+  security:
+    - bearerAuth: []
+  tags:
+    - Fee Recipient
+  parameters:
+      - in: path
+        name: pubkey
+        schema:
+          $ref: "../keymanager-oapi.yaml#/components/schemas/Pubkey"
+        required: true
+  requestBody:
+    content:
+      application/json:
+        schema:
+          $ref: '../keymanager-oapi.yaml#/components/schemas/Ethaddress'
+          required: true
+  responses:
+    "200":
+      description: ok or updated
+      content:
+        application/json:
+          schema:
+            title: SetFeeRecipientResponse
+            type: string
+            example: "updated"
+    "400":
+      $ref: "../keymanager-oapi.yaml#/components/responses/BadRequest"
+    "401":
+      $ref: "../keymanager-oapi.yaml#/components/responses/Unauthorized"
+    "403":
+      $ref: "../keymanager-oapi.yaml#/components/responses/Forbidden"
+    "404":
+      $ref: "../keymanager-oapi.yaml#/components/responses/NotFound"
+    "500":
+      $ref: "../keymanager-oapi.yaml#/components/responses/InternalError"

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/{pubkey}:
+    $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'
+    FeeRecipient:
+      $ref: './types/fee_recipient.yaml'
     SignerDefinition:
       $ref: './types/signer_definition.yaml'
     ImportRemoteSignerDefinition:
@@ -70,21 +78,24 @@ components:
         application/json:
           schema:
             $ref: "#/components/schemas/ErrorResponse"
-
     Unauthorized:
       description: "Unauthorized, no token is found"
       content:
         application/json:
           schema:
             $ref: "#/components/schemas/ErrorResponse"
-
     Forbidden:
       description: "Forbidden, a token is found but is invalid"
       content:
         application/json:
           schema:
             $ref: "#/components/schemas/ErrorResponse"
-
+    NotFound:
+      description: "Path not found"
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorResponse"
     InternalError:
       description: |
         Internal server error. The server encountered an unexpected error indicative of

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.yaml

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