Add graffiti API

README.md

@@ -29,14 +29,14 @@ such as GUIs, alerts, etc.
 Learn about the Consensus Validator Clients that implement these APIs on the [Ethereum.org](https://ethereum.org/)
 
 ### v1 APIS
-| Validator Client/Remote Managers | local keymanager | remote keymanager | fee recipient | gas limit  |
-| -------------------------------- | ---------------- | ----------------- | ------------- |------------|
-| Prysm                            | production       | production        | production    | production |
-| Teku                             | production       | production        | production    | production |
-| Lighthouse                       | v2.1.2           | v2.3.0            | v2.4.0        | v3.0.0     |
-| Nimbus                           | production       | production        | 22.7.0        | -          |
-| Lodestar                         | production       | v0.40.0           | production    | production |
-| Web3signer                       | production       | N/A               | N/A           | N/A        |
+| Validator Client/Remote Managers | local keymanager | remote keymanager | fee recipient | gas limit  | graffiti   |
+| -------------------------------- | ---------------- | ----------------- | ------------- |------------|------------|
+| Prysm                            | production       | production        | production    | production | -          |
+| Teku                             | production       | production        | production    | production | -          |
+| Lighthouse                       | v2.1.2           | v2.3.0            | v2.4.0        | v3.0.0     | -          |
+| Nimbus                           | production       | production        | 22.7.0        | -          | -          |
+| Lodestar                         | production       | v0.40.0           | production    | production | production |
+| Web3signer                       | production       | N/A               | N/A           | N/A        | N/A        |
 
 ## Use Cases
 

apis/graffiti.yaml

@@ -0,0 +1,122 @@
+get:
+  operationId: getGraffiti
+  summary: Get Graffiti
+  description: |
+    Get the graffiti for an individual validator. This graffiti is the one used by the
+    validator when proposing blocks. If no graffiti has been set explicitly for
+    a key then the process-wide default will be returned.
+  security:
+    - bearerAuth: []
+  tags:
+    - Graffiti
+  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: ListGraffitiResponse
+            type: object
+            required: [data]
+            properties:
+              data:
+                type: object
+                required: [graffiti]
+                properties:
+                  pubkey:
+                    $ref: "../keymanager-oapi.yaml#/components/schemas/Pubkey"
+                  graffiti:
+                    $ref: "../keymanager-oapi.yaml#/components/schemas/Graffiti"
+    "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"
+
+post:
+  operationId: setGraffiti
+  summary: Set Graffiti
+  description: |
+    Set the graffiti for an individual validator. This graffiti will be used instead
+    of the process-wide default by the validator when proposing blocks.
+  security:
+    - bearerAuth: []
+  tags:
+    - Graffiti
+  parameters:
+    - in: path
+      name: pubkey
+      schema:
+        $ref: "../keymanager-oapi.yaml#/components/schemas/Pubkey"
+      required: true
+  requestBody:
+    content:
+      application/json:
+        schema:
+          title: SetGraffitiRequest
+          type: object
+          required: [graffiti]
+          properties:
+            graffiti:
+              $ref: "../keymanager-oapi.yaml#/components/schemas/Graffiti"
+  responses:
+    "202":
+      description: successfully 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"
+
+delete:
+  operationId: deleteGraffiti
+  summary: Delete Configured Graffiti
+  description: |
+    Delete the configured graffiti for the specified public key.
+  security:
+    - bearerAuth: []
+  tags:
+    - Graffiti
+  parameters:
+    - in: path
+      name: pubkey
+      schema:
+        $ref: "../keymanager-oapi.yaml#/components/schemas/Pubkey"
+      required: true
+  responses:
+    "204":
+      description: Successfully removed the graffiti, or there was no graffiti set for the requested public key.
+    "400":
+      $ref: "../keymanager-oapi.yaml#/components/responses/BadRequest"
+    "401":
+      $ref: "../keymanager-oapi.yaml#/components/responses/Unauthorized"
+    "403":
+      description: A graffiti was found, but cannot be removed. This may be because the graffit was in configuration files that cannot be updated.
+      content:
+        application/json:
+          schema:
+            $ref: "../keymanager-oapi.yaml#/components/schemas/ErrorResponse"
+    "404":
+      description: The key was not found on the server, nothing to delete.
+      content:
+        application/json:
+          schema:
+            $ref: "../keymanager-oapi.yaml#/components/schemas/ErrorResponse"
+    "500":
+      $ref: "../keymanager-oapi.yaml#/components/responses/InternalError"

keymanager-oapi.yaml

@@ -35,6 +35,8 @@ tags:
     description: Set of endpoints for management of fee recipient.
   - name: Gas Limit
     description: Set of endpoints for management of gas limits.
+  - name: Graffiti
+    description: Set of endpoints for management of graffiti.
   - name: Local Key Manager
     description: Set of endpoints for key management of local keys.
   - name: Remote Key Manager
@@ -51,6 +53,8 @@ paths:
     $ref:  './apis/fee_recipient.yaml'
   /eth/v1/validator/{pubkey}/gas_limit:
     $ref:  './apis/gas_limit.yaml'
+  /eth/v1/validator/{pubkey}/graffiti:
+    $ref:  './apis/graffiti.yaml'
   /eth/v1/validator/{pubkey}/voluntary_exit:
     $ref: './apis/voluntary_exit.yaml'
 
@@ -72,6 +76,8 @@ components:
       $ref: './types/fee_recipient.yaml'
     GasLimit:
       $ref: './types/gas_limit.yaml'
+    Graffiti:
+      $ref: './types/graffiti.yaml'
     Uint64:
       $ref: './types/uint.yaml#/Uint64'
     SignerDefinition:

types/graffiti.yaml

@@ -0,0 +1,3 @@
+type: string
+description: "Arbitrary data validator wants to include in block."
+example: "plain text value"