Integrate the Web3Signer REST API spec.

.github/workflows/sync-openapi.yml

@@ -0,0 +1,88 @@
+---
+name: Sync OpenAPI specs
+
+on:
+  schedule:
+    - cron: "0 2 * * *"  # Daily at 2 AM UTC
+  workflow_dispatch: {}
+
+concurrency:
+  group: sync-openapi-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  sync:
+    name: Sync OpenAPI specs from Web3Signer
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Fetch OpenAPI specs from Web3Signer
+        run: |
+          mkdir -p src/openapi-specs
+          # Clone only the openapi-specs directory using sparse checkout
+          git clone --depth 1 --filter=blob:none --sparse \
+            https://github.com/Consensys/web3signer.git temp-web3signer
+          cd temp-web3signer
+          git sparse-checkout set openapi-specs
+          cd ..
+
+          # Copy the specs to the build-time directory used by the docs generator
+          rm -rf src/openapi-specs/eth1 src/openapi-specs/eth2
+          cp -r temp-web3signer/openapi-specs/eth1 src/openapi-specs/
+          cp -r temp-web3signer/openapi-specs/eth2 src/openapi-specs/
+
+          # Cleanup
+          rm -rf temp-web3signer
+
+      - name: Bundle OpenAPI specs
+        run: |
+          node src/scripts/normalize_openapi_servers.cjs
+          npx --yes @redocly/cli@2.12.6 bundle src/openapi-specs/eth2/web3signer.yaml -o src/openapi-specs/eth2-bundled.yaml
+          npx --yes @redocly/cli@2.12.6 bundle src/openapi-specs/eth1/web3signer.yaml -o src/openapi-specs/eth1-bundled.yaml
+
+      - name: Generate API documentation
+        run: |
+          npm run clean-api-docs
+          npm run gen-api-docs
+
+      - name: Check for changes
+        id: changes
+        run: |
+          if git diff --quiet docs/reference/api/; then
+            echo "has_changes=false" >> $GITHUB_OUTPUT
+          else
+            echo "has_changes=true" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Create Pull Request
+        if: steps.changes.outputs.has_changes == 'true'
+        uses: peter-evans/create-pull-request@v6
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          commit-message: "chore: sync OpenAPI specs from web3signer"
+          title: "chore: Sync OpenAPI specs from Web3Signer"
+          body: |
+            This PR updates the OpenAPI specifications from the [Web3Signer repository](https://github.com/Consensys/web3signer).
+            Changes were detected in the OpenAPI specs and the API documentation has been regenerated.
+          branch: chore/sync-openapi-specs
+          base: main
+          delete-branch: true
+          labels: |
+            documentation
+            automated
+          team-reviewers: |
+            protocol-pliny
+

.gitignore

@@ -9,6 +9,11 @@
 .cache-loader
 .idea
 
+# OpenAPI specs fetched from Web3Signer repo (generated at build time)
+src/openapi-specs/eth1/
+src/openapi-specs/eth2/
+src/openapi-specs/*-bundled.yaml
+
 # Misc
 .DS_Store
 .env.local

docs/concepts/architecture.md

@@ -14,7 +14,7 @@ Web3Signer is a remote signing client comprised of three main components:
 ## The remote signer
 
 The remote signer [loads private keys](../how-to/load-keys.md) into memory and responds to signature requests.
-If you are using an [HSM](../how-to/store-keys/hsm/_category_.json) or a [vault](../how-to/store-keys/vaults/_category_.json) for execution layer signing, the keys stay at rest.
+If you are using an [HSM](/how-to/store-keys/hsm) or a [vault](/how-to/store-keys/vaults) for execution layer signing, the keys stay at rest.
 This component communicates with the slashing database, the APIs, and the keystore (if used), to coordinate remote signing.
 
 ## The slashing database
@@ -24,5 +24,5 @@ Database locking ensures that when multiple Web3Signer instances load the same k
 
 ## The APIs
 
-Web3Signer supports REST and [JSON-RPC APIs](../reference/api/_category_.json) to sign consensus layer and execution layer payloads
+Web3Signer supports REST and [JSON-RPC APIs](../reference/api/json-rpc.md) to sign consensus layer and execution layer payloads
 respectively. These connections should be carefully secured. Web3Signer offers [TLS communication](../how-to/configure-tls.md).

docs/reference/api/eth1/eth-1-list.api.mdx

@@ -0,0 +1,64 @@
+---
+id: eth-1-list
+title: "List of available ETH1 SECP256K1 Public Keys"
+description: "Returns the ETH1 SECP256K1 public keys for the private keys that have been loaded into Web3Signer"
+sidebar_label: "List of available ETH1 SECP256K1 Public Keys"
+hide_title: true
+hide_table_of_contents: true
+api: eJy9k99v0zAQx/8V655NkxSGRN7GVEG1CVV0iIeqQtf02pg5tmdfU6Io/zu6tLBu7Jm8xPH9vu8nPTDuE5QrWBw21lTqljpYa9hSqqIJbLyDEr4SH6JLimtSs/vPhVrObhbTq/e3hQqnsAfqktr5OLqEaFpkOl1yjaxqbEltiJyyHre0VcaxV99p83Zp9o4iaPCBIkq9+RZKkCo/7ubLe9AQKQXvEiUoe5jmubye92dNYuV3l82Ahso7JsfijiFYU43ps59JYnpIVU0Nyom7QFACxogdaDBMTbq4TxyN28Mgj4Z3rzXwEbcq0uOBEssWGmQYNFy95jp3TNGhvZheJYotRUUx+ghSpCGuvexhTwwaAnINJWQYTNYWGXFdZKdZb0+jnhKIjj0cooUSYNB/jjVzKLPM+gpt7ROXH/I8h2GtwbidHwc1bGXSi5ZGma8Xc3jJgtjP1shmhxVLA1L9ZC8mxSQHDdZU5BJJeoeNZL8OWNWkpqP5WWvH43GCo3Xi4z47h6bsbn4z+7KcvZlO8knNjR13E3ziBt1F4ruz/Niisbix/0D6xHZ6OU//hMl/wfzMFNMvzoJF4wSUcRn9WeYVYDCy0gI0iNQCwJPYaw0iovj1/QYTfYt2GOT68UCxg3K11tBiNLII+Ro01IRbiiMdD9SJFFVFQchq0R5G9l/+IILHXwo/ze5hGH4D6kRjxg==
+sidebar_class_name: "get api-method"
+info_path: reference/api/eth1/web-3-signer-eth-1-api
+custom_edit_url: null
+hide_send_button: true
+---
+
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
+import ParamsDetails from "@theme/ParamsDetails";
+import RequestSchema from "@theme/RequestSchema";
+import StatusCodes from "@theme/StatusCodes";
+import OperationTabs from "@theme/OperationTabs";
+import TabItem from "@theme/TabItem";
+import Heading from "@theme/Heading";
+
+<Heading
+  as={"h1"}
+  className={"openapi__heading"}
+  children={"List of available ETH1 SECP256K1 Public Keys"}
+>
+</Heading>
+
+<MethodEndpoint
+  method={"get"}
+  path={"/api/v1/eth1/publicKeys"}
+  context={"endpoint"}
+>
+
+</MethodEndpoint>
+
+
+
+Returns the ETH1 SECP256K1 public keys for the private keys that have been loaded into Web3Signer
+
+<ParamsDetails
+  parameters={undefined}
+>
+
+</ParamsDetails>
+
+<RequestSchema
+  title={"Body"}
+  body={undefined}
+>
+
+</RequestSchema>
+
+<StatusCodes
+  id={undefined}
+  label={undefined}
+  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"}}}
+>
+
+</StatusCodes>
+
+
+

docs/reference/api/eth1/eth-1-sign.api.mdx

@@ -0,0 +1,72 @@
+---
+id: eth-1-sign
+title: "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"
+sidebar_label: "Signs data for ETH1 SECP256K1 public key"
+hide_title: true
+hide_table_of_contents: true
+api: eJy9VU1v20YQ/SvEnBqUlrikKH4UPTiG0RoJEsN2kIMhFMPdobgpRTK7K8uGoP9ezFKpZFnpsTpRO7Pz8Wbe2y04XFooH+FeLzvdLWERgiIrjR6c7jsovcEGCh0GdW8C11Bw/fCnCO6vr27jdP5BBMO6arUM/qaXwA4kda1JBWiDAY0L+tpf+XL3McBOBYbc2nTWn1m97NCtDUEI/UAGOeONghI4wV/3N398ghAGNLgiR4bL3EKHK4IStKLOcSYDIWiuc0DXQAiGvq+1IQWlM2s6beYDvfguNo2WzdiU630hEIKVDa0Qyi24l4GTWGcYkt1uMcYl69736oU9TtPIvnPUOTbhMLRa+mam3yyn3b4N3VffSDpuz3DrTpNlK1d0roDjvh5Hr0UIqJTmNNjevory9jY942po6ZAinWRJmot5Nk+iLMnTlH5Not1uzGSHvrNjqDiK/KVXKDb0HFAne0UqGJPwmI/HeQSHo2c3HVrU3W+BbNBYcr+vXX2Rn8XlR81HJUP0XCUVYpYKFWEhkljWVCQ0o0SldV1EWSqEEFFESZYXSmIsClSUYjxTcUaiUGJeJUmaiFmhUORJQkU1L0RVJfk8mVGuZDSbzYuKsiiJRRIX0VwWcaYyEjgrqpmYZUk0F3GeZZWcV3EuIpnXcRQrrLMiUQKrSM2rVFaxUGlcF5TGlOdJnhZ5nmGqCvDAzs5h+R6ZFH63eDNX6MC7zt663o484x3uevZed4qd03NxbzpHpsM2+EpVwhwmE1gyT2QCMqY3fi1W5JqeCTf01i8jc6iEKQ56+iSm5Box5bFOtwe+7ZgpPtBIyLVpoQTYhT8+G+eGcjpte4lt01tXFlEUAXOI2XB34NH16VIeTV93de/XQju/A0ddePW5vL2Bc0q1txqna5TOQghc6GgXEzGJIIRWS+qsz7tXk8sBZUNB7M2vuthsNhP01klvltP9VTv9eHN1/en++iKeRJPGrVoPJ6O4wu4o8Il4/lQ4T3vZHhj0Pwnwnn8HtvIUPBTb/Vo8Ag6aARUQAq8GL8KonOWRHC9C4Kmz/3ZboaUvpt3t+Pj7mswLlI+LEJ7QaKx4so9bUNryt4KyxtaeavYxFL/c7VXwXfCfSn62mf0hdoz2E7Zr/gchMPyvHpTdYhdCQ6jI+PpGh6uxiosHDnMI8EbtmQjjjUspaXBHvj+XQmbHv2S8/Xz/ACFU+6dm1Su+bHDDzxtuxqp7D4/XaH+2hRa75RqX7DsWwr9/AP7NmBw=
+sidebar_class_name: "post api-method"
+info_path: reference/api/eth1/web-3-signer-eth-1-api
+custom_edit_url: null
+hide_send_button: true
+---
+
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
+import ParamsDetails from "@theme/ParamsDetails";
+import RequestSchema from "@theme/RequestSchema";
+import StatusCodes from "@theme/StatusCodes";
+import OperationTabs from "@theme/OperationTabs";
+import TabItem from "@theme/TabItem";
+import Heading from "@theme/Heading";
+
+<Heading
+  as={"h1"}
+  className={"openapi__heading"}
+  children={"Signs data for ETH1 SECP256K1 public key"}
+>
+</Heading>
+
+<MethodEndpoint
+  method={"post"}
+  path={"/api/v1/eth1/sign/{identifier}"}
+  context={"endpoint"}
+>
+
+</MethodEndpoint>
+
+
+
+Signs data for the ETH1 SECP256K1 public key specified as part of the URL and returns the signature
+
+<Heading
+  id={"request"}
+  as={"h2"}
+  className={"openapi-tabs__heading"}
+  children={"Request"}
+>
+</Heading>
+
+<ParamsDetails
+  parameters={[{"name":"identifier","in":"path","required":true,"description":"Key for which data to sign","schema":{"type":"string"}}]}
+>
+
+</ParamsDetails>
+
+<RequestSchema
+  title={"Body"}
+  body={{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"string"}},"required":["data"],"additionalProperties":{"type":"string"}},"example":{"data":5.735816763073855e+30}}}}}
+>
+
+</RequestSchema>
+
+<StatusCodes
+  id={undefined}
+  label={undefined}
+  responses={{"200":{"description":"hex encoded string of signature","content":{"text/plain; charset=utf-8":{"schema":{"type":"string"},"example":"0xb3baa751d0a9132cfe93e4e3d5ff9075111100e3789dca219ade5a24d27e19d16b3353149da1833e9b691bb38634e8dc04469be7032132906c927d7e1a49b414730612877bc6b2810c8f202daf793d1ab0d6b5cb21d52f9e52e883859887a5d9"}}},"400":{"description":"Bad request format"},"404":{"description":"Public Key not found"},"500":{"description":"Internal Web3Signer server error"}}}
+>
+
+</StatusCodes>
+
+
+

docs/reference/api/eth1/healthcheck.api.mdx

@@ -0,0 +1,64 @@
+---
+id: healthcheck
+title: "Server Health Status"
+description: "Web3Signer server health status"
+sidebar_label: "Server Health Status"
+hide_title: true
+hide_table_of_contents: true
+api: eJztVMGK2zAQ/RUzZzX2ZumhvoUQmtClFLKlh5CDIs/G2pUlVRonDcb/XsZWu0l2YUtvhZ4kNHpPb+aNpgOS+wjlBtYYDhiyJUpDdbYmSW2ErYAKowrak3YWSviGu9u13lsMWRwB9QiII0CA8xgk315VUMJyMbu7X86Xi/knEBAwemcjRig7mBYFL5f861MkbDIdE+8JBChnCS3xZem90Wqgzx8jIzqIqsZG8o5OHqEEt3tERSDABxZDenwvKXy+Fylou4frFC8T6gWoGtXTOVCGIE8vcEZHytxDAmYJJUATNgP6Uo6u3paSqHTFMv5Sf9/3AlxLyjX4NphqzNwBgzQmSyDOKXEOOQETkibDNGO7zNM5R94Xty9tnVFmUHJ9LGY+OIVVG5Btbu1/o/9Fo3sBDVLt+JPvcTBBUg0l5CPFyCBgnBI8YTpog4ESoBe/tjWRL/PcOCVN7SKVH4qigH4rQNsHNySRnj+bO4v75U02+7J6kRLHUzSQfpCK2BV+fYzfTG4mBQgwWqGNQ42s5FrBzEtVYzYdwhfSjsfjRA7RiQv7PEFjfreaLz6vF++mk2JSU2OGWnkXqZH2jPjVoXqlu3vu+z8Yr8lVwh+UeyO15Y4ZJHfJgQ2cO7AVwJXl467byYhfg+l7Pv7eYjhBudkKOMig5Y4Lvdn2gvEVhsGyJzxxfZRCzx4fpGmHj3H9Pdmz3/3wcXEPff8TDxUxHw==
+sidebar_class_name: "get api-method"
+info_path: reference/api/eth1/web-3-signer-eth-1-api
+custom_edit_url: null
+hide_send_button: true
+---
+
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
+import ParamsDetails from "@theme/ParamsDetails";
+import RequestSchema from "@theme/RequestSchema";
+import StatusCodes from "@theme/StatusCodes";
+import OperationTabs from "@theme/OperationTabs";
+import TabItem from "@theme/TabItem";
+import Heading from "@theme/Heading";
+
+<Heading
+  as={"h1"}
+  className={"openapi__heading"}
+  children={"Server Health Status"}
+>
+</Heading>
+
+<MethodEndpoint
+  method={"get"}
+  path={"/healthcheck"}
+  context={"endpoint"}
+>
+
+</MethodEndpoint>
+
+
+
+Web3Signer server health status
+
+<ParamsDetails
+  parameters={undefined}
+>
+
+</ParamsDetails>
+
+<RequestSchema
+  title={"Body"}
+  body={undefined}
+>
+
+</RequestSchema>
+
+<StatusCodes
+  id={undefined}
+  label={undefined}
+  responses={{"200":{"description":"System is healthy","content":{"application/json":{"schema":{"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"}},"title":"HealthCheck"}}}},"503":{"description":"At least one procedure is unhealthy","content":{"application/json":{"schema":{"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"}},"title":"HealthCheck"}}}}}}
+>
+
+</StatusCodes>
+
+
+

docs/reference/api/eth1/reload.api.mdx

@@ -0,0 +1,64 @@
+---
+id: reload
+title: "Reload signer keys asynchronously"
+description: "Reload signer keys asynchronously"
+sidebar_label: "Reload signer keys asynchronously"
+hide_title: true
+hide_table_of_contents: true
+api: eJyNUU1r20AQ/SvinbeS7NJDdDOJoSahCXFKD0aHtTy2lqx31Z1RXCH038vKCtghh5x2mTcf76OH6AOj2OCZrNe7ZG0OjkJyTx2jVNgRV8E0YrxD8d7D555X6jjR3LmqDt75lm0HBd9Q0LF/tYsTy4fHxR0UAnHjHROj6DHP8/hcL7/V1iaGE26ripj3rcWg8OOz1pUTCk7b5A9tv0+MmcIbhYRC8AHDoHAkqX3k0HgWKDRaahTIwigCCueJKL5HGywKYFDv31qkKbLM+krb2rMUN3meYygVjNv7SEmMWEKBCw7Ll5+zZPG0wkfjIj6hQcxeV8JQiNfP+CydpTkUrKnIMcX1Th/j9kWjq5qS+QhfUTudTqke0dSHQzaNcvawul3+Wi+/zdM8reVoRzOiB0ftLhZ/JcsrET0q74ScfHFYuibeEfonWWO1cTHOUUE/ZbHBlEWpED2Olb7faqbfwQ5DLP9tKXQoNqXCmw5Gb6Plm/Iy3qfH9QuG4T9XAfEQ
+sidebar_class_name: "post api-method"
+info_path: reference/api/eth1/web-3-signer-eth-1-api
+custom_edit_url: null
+hide_send_button: true
+---
+
+import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
+import ParamsDetails from "@theme/ParamsDetails";
+import RequestSchema from "@theme/RequestSchema";
+import StatusCodes from "@theme/StatusCodes";
+import OperationTabs from "@theme/OperationTabs";
+import TabItem from "@theme/TabItem";
+import Heading from "@theme/Heading";
+
+<Heading
+  as={"h1"}
+  className={"openapi__heading"}
+  children={"Reload signer keys asynchronously"}
+>
+</Heading>
+
+<MethodEndpoint
+  method={"post"}
+  path={"/reload"}
+  context={"endpoint"}
+>
+
+</MethodEndpoint>
+
+
+
+Reload signer keys asynchronously
+
+<ParamsDetails
+  parameters={undefined}
+>
+
+</ParamsDetails>
+
+<RequestSchema
+  title={"Body"}
+  body={undefined}
+>
+
+</RequestSchema>
+
+<StatusCodes
+  id={undefined}
+  label={undefined}
+  responses={{"200":{"description":"Call is successful"},"500":{"description":"Internal Web3Signer server error"}}}
+>
+
+</StatusCodes>
+
+
+