Fee Recipient API

apis/fee_recipient.yaml

@@ -0,0 +1,101 @@
+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: API only works POST MERGE(Bellatrix) 
+  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"
+    "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
+  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: Success response
+      content:
+        application/json:
+          schema:
+            title: SetFeeRecipientResponse
+            type: object
+            required: [data]
+            properties:
+              data:
+                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
+                  FeeRecipient:
+                    $ref: "../keymanager-oapi.yaml#/components/schemas/FeeRecipient"
+    "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"

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:

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'