From e0332ebc8bf1751a6c045ef9ae2664f73dfd43f8 Mon Sep 17 00:00:00 2001 From: Nico Flaig Date: Sun, 5 Nov 2023 20:37:28 +0100 Subject: [PATCH 1/7] Add graffiti API --- README.md | 19 +++---- apis/graffiti.yaml | 122 +++++++++++++++++++++++++++++++++++++++++++ keymanager-oapi.yaml | 6 +++ types/graffiti.yaml | 3 ++ 4 files changed, 141 insertions(+), 9 deletions(-) create mode 100644 apis/graffiti.yaml create mode 100644 types/graffiti.yaml diff --git a/README.md b/README.md index 536bfba..7bcf610 100644 --- a/README.md +++ b/README.md @@ -29,14 +29,15 @@ 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 | v1.12.0 | +| Web3signer | production | N/A | N/A | N/A | N/A | ## Use Cases @@ -50,7 +51,7 @@ Further detail on expected behavior and error states of the APIs are listed in t To render the spec in a browser you will need an HTTP server to serve the `index.html` file. Rendering occurs client-side in JavaScript, so no changes are required to the HTML file between -edits. +edits. ##### Python diff --git a/apis/graffiti.yaml b/apis/graffiti.yaml new file mode 100644 index 0000000..bbea92f --- /dev/null +++ b/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" diff --git a/keymanager-oapi.yaml b/keymanager-oapi.yaml index 212b595..5bd9905 100644 --- a/keymanager-oapi.yaml +++ b/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: diff --git a/types/graffiti.yaml b/types/graffiti.yaml new file mode 100644 index 0000000..c8a84f6 --- /dev/null +++ b/types/graffiti.yaml @@ -0,0 +1,3 @@ +type: string +description: "Arbitrary data validator wants to include in block." +example: "plain text value" From 861deb173303eaf2d9ee9b500e34b232ccdbfe93 Mon Sep 17 00:00:00 2001 From: Nico Flaig Date: Thu, 9 Nov 2023 20:52:50 +0100 Subject: [PATCH 2/7] Update graffiti API descriptions Co-authored-by: Lion - dapplion <35266934+dapplion@users.noreply.github.com> --- apis/graffiti.yaml | 7 +++---- types/graffiti.yaml | 2 +- 2 files changed, 4 insertions(+), 5 deletions(-) diff --git a/apis/graffiti.yaml b/apis/graffiti.yaml index bbea92f..16648ca 100644 --- a/apis/graffiti.yaml +++ b/apis/graffiti.yaml @@ -3,8 +3,8 @@ get: 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. + validator when proposing blocks. If no graffiti is set explicitly, returns + the process-wide default. security: - bearerAuth: [] tags: @@ -48,8 +48,7 @@ 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. + Set the graffiti for an individual validator. security: - bearerAuth: [] tags: diff --git a/types/graffiti.yaml b/types/graffiti.yaml index c8a84f6..57b74da 100644 --- a/types/graffiti.yaml +++ b/types/graffiti.yaml @@ -1,3 +1,3 @@ type: string -description: "Arbitrary data validator wants to include in block." +description: "Arbitrary data to set in the graffiti field of BeaconBlockBody" example: "plain text value" From 70d3ce16677d1ff6cbf9b2d5cf4c3b4070d09d51 Mon Sep 17 00:00:00 2001 From: Nico Flaig Date: Thu, 9 Nov 2023 20:56:30 +0100 Subject: [PATCH 3/7] Update title of graffiti response schema --- apis/graffiti.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apis/graffiti.yaml b/apis/graffiti.yaml index 16648ca..1841dfb 100644 --- a/apis/graffiti.yaml +++ b/apis/graffiti.yaml @@ -21,7 +21,7 @@ get: content: application/json: schema: - title: ListGraffitiResponse + title: GraffitiResponse type: object required: [data] properties: From e1c7031ad23aeae2fe8c39f1fe5f2910bf6e418c Mon Sep 17 00:00:00 2001 From: Nico Flaig Date: Thu, 9 Nov 2023 21:04:55 +0100 Subject: [PATCH 4/7] Update Lodestar versions in API support table --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 7bcf610..0d1d911 100644 --- a/README.md +++ b/README.md @@ -36,7 +36,7 @@ Learn about the Consensus Validator Clients that implement these APIs on the [Et | 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 | v1.12.0 | +| Lodestar | v0.35.0 | v0.40.0 | v1.2.0 | v1.2.0 | v1.12.0 | | Web3signer | production | N/A | N/A | N/A | N/A | ## Use Cases From f7ea96f6c8dbd5eb5f56a46d8c45465513e313f0 Mon Sep 17 00:00:00 2001 From: Nico Flaig Date: Fri, 10 Nov 2023 16:42:11 +0100 Subject: [PATCH 5/7] More detailed graffiti API descriptions --- apis/graffiti.yaml | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/apis/graffiti.yaml b/apis/graffiti.yaml index 1841dfb..9820178 100644 --- a/apis/graffiti.yaml +++ b/apis/graffiti.yaml @@ -48,7 +48,8 @@ post: operationId: setGraffiti summary: Set Graffiti description: | - Set the graffiti for an individual validator. + 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: @@ -87,7 +88,8 @@ delete: operationId: deleteGraffiti summary: Delete Configured Graffiti description: | - Delete the configured graffiti for the specified public key. + Delete the configured graffiti for the specified public key. The process-wide default + will be used by the validator when proposing blocks. security: - bearerAuth: [] tags: From 327c747951e0ba8a78cdb6597a32b37fa7fb7633 Mon Sep 17 00:00:00 2001 From: Nico Flaig Date: Mon, 20 Nov 2023 22:01:07 +0100 Subject: [PATCH 6/7] Remove graffiti precedence for block proposal from API descriptions --- apis/graffiti.yaml | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/apis/graffiti.yaml b/apis/graffiti.yaml index 9820178..1ea965b 100644 --- a/apis/graffiti.yaml +++ b/apis/graffiti.yaml @@ -2,9 +2,7 @@ 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 is set explicitly, returns - the process-wide default. + Get the graffiti for an individual validator. security: - bearerAuth: [] tags: @@ -48,8 +46,7 @@ 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. + Set the graffiti for an individual validator. security: - bearerAuth: [] tags: @@ -88,8 +85,7 @@ delete: operationId: deleteGraffiti summary: Delete Configured Graffiti description: | - Delete the configured graffiti for the specified public key. The process-wide default - will be used by the validator when proposing blocks. + Delete the configured graffiti for the specified public key. security: - bearerAuth: [] tags: From 7e9f2283dcad4b99b6cbc93b4ebb96351fd4437f Mon Sep 17 00:00:00 2001 From: Nico Flaig Date: Thu, 23 Nov 2023 10:59:46 +0100 Subject: [PATCH 7/7] Update description of getGraffiti API --- apis/graffiti.yaml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/apis/graffiti.yaml b/apis/graffiti.yaml index 1ea965b..8098bfd 100644 --- a/apis/graffiti.yaml +++ b/apis/graffiti.yaml @@ -2,7 +2,8 @@ get: operationId: getGraffiti summary: Get Graffiti description: | - Get the graffiti for an individual validator. + Get the graffiti for an individual validator. If no graffiti is set + explicitly, returns the process-wide default. security: - bearerAuth: [] tags: @@ -104,7 +105,7 @@ delete: "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. + description: A graffiti was found, but cannot be removed. This may be because the graffiti was in configuration files that cannot be updated. content: application/json: schema: