Add gas limit API (#39)

README.md

@@ -28,14 +28,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 |
-| -------------------------------- | ---------------- | ----------------- | ------------- |
-| Prysm                            | production       | production        | develop       |
-| Teku                             | production       | production        | production    |
-| Lighthouse                       | v2.1.2           | v2.3.0            | v2.4.0        |
-| Nimbus                           | production       | production        | inprogress    |
-| Lodestar                         | production       | v0.40.0           | inprogress    |
-| Web3signer                       | production       | N/A               | N/A           |
+| Validator Client/Remote Managers | local keymanager | remote keymanager | fee recipient | gas limit |
+| -------------------------------- | ---------------- | ----------------- | ------------- | --------- |
+| Prysm                            | production       | production        | develop       | -         |
+| Teku                             | production       | production        | production    | -         |
+| Lighthouse                       | v2.1.2           | v2.3.0            | v2.4.0        | -         |
+| Nimbus                           | production       | production        | inprogress    | -         |
+| Lodestar                         | production       | v0.40.0           | inprogress    | -         |
+| Web3signer                       | production       | N/A               | N/A           | N/A       |
 
 ## Use Cases
 

apis/gas_limit.yaml

@@ -0,0 +1,126 @@
+get:
+  operationId: GetGasLimit
+  summary: Get Gas Limit.
+  description: |
+    Get the execution gas limit for an individual validator. This gas limit is the one used by the
+    validator when proposing blocks via an external builder. If no limit has been set explicitly for
+    a key then the process-wide default will be returned.
+
+    The server may return a 400 status code if no external builder is configured.
+
+    WARNING: The gas_limit is not used on Phase0 or Altair networks.
+  security:
+    - bearerAuth: []
+  tags:
+    - Gas Limit
+  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: ListGasLimitResponse
+            type: object
+            required: [data]
+            properties:
+              data:
+                $ref: "../keymanager-oapi.yaml#/components/schemas/GasLimit"
+    "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: SetGasLimit
+  summary: Set Gas Limit.
+  description: |
+    Set the gas limit for an individual validator. This limit will be propagated to the beacon
+    node for use on future block proposals. The beacon node is responsible for informing external
+    block builders of the change.
+
+    The server may return a 400 status code if no external builder is configured.
+
+    WARNING: The gas_limit is not used on Phase0 or Altair networks.
+  security:
+    - bearerAuth: []
+  tags:
+    - Gas Limit
+  parameters:
+      - in: path
+        name: pubkey
+        schema:
+          $ref: "../keymanager-oapi.yaml#/components/schemas/Pubkey"
+        required: true
+  requestBody:
+    content:
+      application/json:
+        schema:
+            title: SetGasLimitRequest
+            type: object
+            required: [gas_limit]
+            properties:
+              gas_limit:
+                $ref: '../keymanager-oapi.yaml#/components/schemas/Uint64'
+  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: DeleteGasLimit
+  summary: Delete Configured Gas Limit
+  description: |
+    Delete a configured gas limit for the specified public key.
+
+    The server may return a 400 status code if no external builder is configured.
+  security:
+    - bearerAuth: [ ]
+  tags:
+    - Gas Limit
+  parameters:
+    - in: path
+      name: pubkey
+      schema:
+        $ref: "../keymanager-oapi.yaml#/components/schemas/Pubkey"
+      required: true
+  responses:
+    "204":
+      description: Successfully removed the gas limit, or there was no gas limit 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 gas limit was found, but cannot be removed. This may be because the gas limit 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

@@ -33,6 +33,8 @@ servers:
 tags:
   - name: Fee Recipient
     description: Set of endpoints for management of fee recipient.
+  - name: Gas Limit
+    description: Set of endpoints for management of gas limits.
   - name: Local Key Manager
     description: Set of endpoints for key management of local keys.
   - name: Remote Key Manager
@@ -45,6 +47,8 @@ paths:
     $ref:  './apis/remote_keystores.yaml'
   /eth/v1/validator/{pubkey}/feerecipient:
     $ref:  './apis/fee_recipient.yaml'
+  /eth/v1/validator/{pubkey}/gas_limit:
+    $ref:  './apis/gas_limit.yaml'
 
 components:
   securitySchemes:
@@ -62,6 +66,10 @@ components:
       $ref: './types/keystore.yaml'
     FeeRecipient:
       $ref: './types/fee_recipient.yaml'
+    GasLimit:
+      $ref: './types/gas_limit.yaml'
+    Uint64:
+      $ref: './types/uint.yaml#/Uint64'
     SignerDefinition:
       $ref: './types/signer_definition.yaml'
     ImportRemoteSignerDefinition:

types/gas_limit.yaml

@@ -0,0 +1,7 @@
+type: object
+required: [gas_limit]
+properties:
+  pubkey:
+    $ref: './public_key.yaml'
+  gas_limit:
+    $ref: './uint.yaml#/Uint64'

types/uint.yaml

@@ -0,0 +1,4 @@
+Uint64:
+  type: string
+  pattern: ^[1-9][0-9]{0,19}$
+  example: "30000000"