[skip ci] OpenAPI Publish [24.6.0]

24.6.0/eth1/web3signer.yaml

@@ -0,0 +1,158 @@
+openapi: 3.0.0
+info:
+  title: 'Web3Signer ETH1 API'
+  description: 'Sign ETH1 Artifacts'
+  version: '24.6.0'
+  license:
+    name: 'Apache 2.0'
+    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
+
+servers:
+  - url: /
+  - url: http://localhost:9000/
+
+paths:
+  /api/v1/eth1/sign/{identifier}:
+    post:
+      tags:
+        - 'Signing'
+      summary: 'Signs data for ETH1 SECP256K1 public key'
+      description: 'Signs data for the ETH1 SECP256K1 public key specified as part of the URL and returns the signature'
+      operationId: 'ETH1_SIGN'
+      parameters:
+        - name: 'identifier'
+          in: 'path'
+          required: true
+          description: 'Key for which data to sign'
+          schema:
+            type: 'string'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                data:
+                  type: string
+              required:
+                - data
+              additionalProperties:
+                type: string
+            example:
+              data: 0x48656c6c6f2c20776f726c6421
+
+      responses:
+        '200':
+          description: 'hex encoded string of signature'
+          content:
+            text/plain; charset=utf-8:
+              schema:
+                type: string
+              example: '0xb3baa751d0a9132cfe93e4e3d5ff9075111100e3789dca219ade5a24d27e19d16b3353149da1833e9b691bb38634e8dc04469be7032132906c927d7e1a49b414730612877bc6b2810c8f202daf793d1ab0d6b5cb21d52f9e52e883859887a5d9'
+        '404':
+          description: 'Public Key not found'
+        '400':
+          description: 'Bad request format'
+        '500':
+          description: 'Internal Web3Signer server error'
+
+  /api/v1/eth1/publicKeys:
+    get:
+      tags:
+        - 'Public Key'
+      summary: 'List of available ETH1 SECP256K1 Public Keys'
+      description: 'Returns the ETH1 SECP256K1 public keys for the private keys that have been loaded into Web3Signer'
+      operationId: 'ETH1_LIST'
+      responses:
+        '200':
+          description: 'list of public keys'
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: string
+        '400':
+          description: 'Bad request format'
+        '500':
+          description: 'Internal Web3Signer server error'
+
+  /reload:
+    post:
+      tags:
+        - 'Reload Signer Keys'
+      summary: 'Reload signer keys asynchronously'
+      description: 'Reload signer keys asynchronously'
+      operationId: 'RELOAD'
+      responses:
+        '200':
+          description: 'Call is successful'
+        '500':
+          description: 'Internal Web3Signer server error'
+
+  /upcheck:
+    get:
+      tags:
+        - 'Server Status'
+      summary: 'Server Status'
+      description: 'Web3Signer server status'
+      operationId: 'UPCHECK'
+      responses:
+        '200':
+          description: 'OK'
+          content:
+            text/plain; charset=utf-8:
+              schema:
+                type: string
+              example: 'OK'
+        '500':
+          description: 'Internal Web3Signer server error'
+
+  /healthcheck:
+    get:
+      tags:
+        - 'Server Health Status'
+      summary: 'Server Health Status'
+      description: 'Web3Signer server health status'
+      operationId: 'HEALTHCHECK'
+      responses:
+        '200':
+          description: 'System is healthy'
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/HealthCheck"
+        '503':
+          description: 'At least one procedure is unhealthy'
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/HealthCheck"
+
+components:
+  schemas:
+    HealthCheck:
+      type: object
+      properties:
+        status:
+          type: string
+          description: 'health status'
+        checks:
+          type: array
+          description: 'list of status checks'
+          items:
+            properties:
+              id:
+                type: string
+                description: 'status id'
+              status:
+                type: string
+                description: 'health status'
+        outcome:
+          type: string
+          description: 'the overall outcome of health check'
+
+externalDocs:
+  description: 'Web3Signer User Documentation'
+  url: 'https://docs.web3signer.consensys.net/'

24.6.0/eth2/keymanager/paths/keystores.yaml

@@ -0,0 +1,187 @@
+get:
+  operationId: KEYMANAGER_LIST
+  summary: List Keys.
+  description: |
+    List all validating pubkeys known to and decrypted by this keymanager binary
+  security:
+    - bearerAuth: []
+  tags:
+    - Keymanager
+  responses:
+    "200":
+      description: Success response
+      content:
+        application/json:
+          schema:
+            title: ListKeysResponse
+            type: object
+            required: [data]
+            properties:
+              data:
+                type: array
+                items:
+                  type: object
+                  required: [validating_pubkey]
+                  properties:
+                    validating_pubkey:
+                      $ref: "../schemas.yaml#/components/schemas/Pubkey"
+                    derivation_path:
+                      type: string
+                      description: The derivation path (if present in the imported keystore).
+                      example: "m/12381/3600/0/0/0"
+                    readonly:
+                      type: boolean
+                      description: The key associated with this pubkey cannot be deleted from the API
+    "401":
+      $ref: "../schemas.yaml#/components/responses/Unauthorized"
+    "403":
+      $ref: "../schemas.yaml#/components/responses/Forbidden"
+    "500":
+      $ref: "../schemas.yaml#/components/responses/InternalError"
+
+post:
+  operationId: KEYMANAGER_IMPORT
+  summary: Import Keystores.
+  description: |
+    Import keystores generated by the Eth2.0 deposit CLI tooling. `passwords[i]` must unlock `keystores[i]`.
+
+    Users SHOULD send slashing_protection data associated with the imported pubkeys. MUST follow the format defined in
+    EIP-3076: Slashing Protection Interchange Format.
+  security:
+    - bearerAuth: []
+  tags:
+    - Keymanager
+  requestBody:
+    content:
+      application/json:
+        schema:
+          type: object
+          required: [keystores, passwords]
+          properties:
+            keystores:
+              type: array
+              description: JSON-encoded keystore files generated with the Launchpad.
+              items:
+                $ref: "../schemas.yaml#/components/schemas/Keystore"
+            passwords:
+              type: array
+              description: Passwords to unlock imported keystore files. `passwords[i]` must unlock `keystores[i]`.
+              items:
+                type: string
+                example: "ABCDEFGH01234567ABCDEFGH01234567"
+            slashing_protection:
+              $ref: "../schemas.yaml#/components/schemas/SlashingProtectionData"
+  responses:
+    "200":
+      description: Success response
+      content:
+        application/json:
+          schema:
+            title: ImportKeystoresResponse
+            type: object
+            required: [data]
+            properties:
+              data:
+                type: array
+                description: Status result of each `request.keystores` with same length and order of `request.keystores`
+                items:
+                  type: object
+                  required: [status]
+                  properties:
+                    status:
+                      type: string
+                      description: |
+                        - imported: Keystore successfully decrypted and imported to keymanager permanent storage
+                        - duplicate: Keystore's pubkey is already known to the keymanager
+                        - error: Any other status different to the above: decrypting error, I/O errors, etc.
+                      enum:
+                        - imported
+                        - duplicate
+                        - error
+                      example: imported
+                    message:
+                      type: string
+                      description: error message if status == error
+    "400":
+      $ref: "../schemas.yaml#/components/responses/BadRequest"
+    "401":
+      $ref: "../schemas.yaml#/components/responses/Unauthorized"
+    "403":
+      $ref: "../schemas.yaml#/components/responses/Forbidden"
+    "500":
+      $ref: "../schemas.yaml#/components/responses/InternalError"
+
+delete:
+  operationId: KEYMANAGER_DELETE
+  summary: Delete Keys.
+  description: |
+    DELETE must delete all keys from `request.pubkeys` that are known to the keymanager and exist in its
+    persistent storage. Additionally, DELETE must fetch the slashing protection data for the requested keys from
+    persistent storage, which must be retained (and not deleted) after the response has been sent. Therefore in the
+    case of two identical delete requests being made, both will have access to slashing protection data.
+
+    In a single atomic sequential operation the keymanager must:
+    1. Guarantee that key(s) can not produce any more signature; only then
+    2. Delete key(s) and serialize its associated slashing protection data
+
+    DELETE should never return a 404 response, even if all pubkeys from request.pubkeys have no extant keystores
+    nor slashing protection data.
+  security:
+    - bearerAuth: []
+  tags:
+    - Keymanager
+  requestBody:
+    content:
+      application/json:
+        schema:
+          type: object
+          required: [pubkeys]
+          properties:
+            pubkeys:
+              type: array
+              description: List of public keys to delete.
+              items:
+                $ref: "../schemas.yaml#/components/schemas/Pubkey"
+  responses:
+    "200":
+      description: Success response
+      content:
+        application/json:
+          schema:
+            title: DeleteKeysResponse
+            type: object
+            required: [data, slashing_protection]
+            properties:
+              data:
+                type: array
+                description: Deletion status of all keys in `request.pubkeys` in the same order.
+                items:
+                  type: object
+                  required: [status]
+                  properties:
+                    status:
+                      type: string
+                      description: |
+                        - deleted: key was active and removed
+                        - not_active: slashing protection data returned but key was not active
+                        - not_found: key was not found to be removed, and no slashing data can be returned
+                        - error: unexpected condition meant the key could not be removed (the key was actually found, but we couldn't stop using it) - this would be a sign that making it active elsewhere would almost certainly cause you headaches / slashing conditions etc.
+                      enum:
+                        - deleted
+                        - not_active
+                        - not_found
+                        - error
+                      example: deleted
+                    message:
+                      type: string
+                      description: error message if status == error
+              slashing_protection:
+                $ref: "../schemas.yaml#/components/schemas/SlashingProtectionData"
+    "400":
+      $ref: "../schemas.yaml#/components/responses/BadRequest"
+    "401":
+      $ref: "../schemas.yaml#/components/responses/Unauthorized"
+    "403":
+      $ref: "../schemas.yaml#/components/responses/Forbidden"
+    "500":
+      $ref: "../schemas.yaml#/components/responses/InternalError"