Merge branch 'master' into nflaig/clarify-status-codes

.github/workflows/deploy.yaml

@@ -21,11 +21,11 @@ jobs:
       matrix:
         release: ${{fromJson(needs.setup.outputs.releases)}}
     steps:
-      - uses: dsaltares/fetch-gh-release-asset@1.1.0
+      - uses: dsaltares/fetch-gh-release-asset@1.1.2
         with:
-          version: 'tags/${{ matrix.release }}'
-          file: 'beacon-node-oapi.json'
-          target: 'deploy/releases/${{ matrix.release }}/beacon-node-oapi.json'
+          version: "tags/${{ matrix.release }}"
+          file: "beacon-node-oapi.json"
+          target: "deploy/releases/${{ matrix.release }}/beacon-node-oapi.json"
       - name: Save releases (artifact)
         uses: actions/upload-artifact@v3
         with:
@@ -37,8 +37,8 @@ jobs:
     needs: releases
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-node@v2
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
       - run: npm i -g @apidevtools/swagger-cli@4
       - name: Prepare deploy directory
         run: |
@@ -55,7 +55,7 @@ jobs:
       - name: Bundle spec
         run: "swagger-cli bundle ./beacon-node-oapi.yaml -r -t yaml -o ./deploy/beacon-node-oapi.yaml"
       - name: Publish to Github Pages
-        uses: peaceiris/actions-gh-pages@v3
+        uses: peaceiris/actions-gh-pages@v4
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: ./deploy

.github/workflows/main.yml

@@ -1,18 +1,23 @@
 name: CI
 
-on: [push, pull_request]
+on:
+  push:
+    branches:
+      - "master"
+  pull_request:
+  workflow_dispatch:
 
 jobs:
   build:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v2
-    - uses: actions/setup-node@v2
-    - run: npm i -g @apidevtools/swagger-cli@4 @redocly/cli@1.0.0-beta.111
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+      - run: npm i -g @apidevtools/swagger-cli@4 @redocly/cli@1.19.0
 
-    - name: Lint spec
-      run: redocly lint ./beacon-node-oapi.yaml
+      - name: Lint spec
+        run: redocly lint ./beacon-node-oapi.yaml
 
-    - name: Bundle spec
-      run: "swagger-cli bundle ./beacon-node-oapi.yaml -r -t yaml -o ./deploy/beacon-node-oapi.yaml"
+      - name: Bundle spec
+        run: "swagger-cli bundle ./beacon-node-oapi.yaml -r -t yaml -o ./deploy/beacon-node-oapi.yaml"

.github/workflows/pre-release.yaml

@@ -0,0 +1,49 @@
+name: Pre-release
+
+on:
+  push:
+    tags:
+      - "v*-(alpha|beta|rc).*"
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+      - run: npm i -g @apidevtools/swagger-cli@4
+      - name: Update Spec version
+        run: "sed -i 's/version: \"Dev/version: \"${{ github.ref_name }}/' ./beacon-node-oapi.yaml"
+      - name: Bundle yaml spec
+        run: "swagger-cli bundle ./beacon-node-oapi.yaml -r -t yaml -o ./deploy/beacon-node-oapi.yaml"
+      - name: Bundle json spec
+        run: "swagger-cli bundle ./beacon-node-oapi.yaml -r -t json -o ./deploy/beacon-node-oapi.json"
+      - name: Create Release Notes
+        run: |
+          echo "The following changes are included in this release:" > release-notes.md
+          awk '/^## Development Version/ {flag=1; next} /^## / {flag=0} flag { \
+          if ($0 ~ /\| \[#/) {sub(/^\| /, "- "); sub(/\| .*$/, ""); sub(/[[:space:]]+$/, ""); print}}' CHANGES.md >> release-notes.md
+      - name: Create Release
+        id: create_release
+        uses: softprops/action-gh-release@v2
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          name: ${{ github.ref_name }}
+          tag_name: ${{ github.ref_name }}
+          body_path: "release-notes.md"
+          draft: false
+          prerelease: true
+          files: |
+            ./deploy/beacon-node-oapi.yaml
+            ./deploy/beacon-node-oapi.json
+          fail_on_unmatched_files: true
+      - name: Rollback Release
+        if: failure()
+        uses: author/action-rollback@1.0.4
+        with:
+          release_id: ${{ steps.create_release.outputs.id }}
+          tag: ${{ github.ref }}
+          delete_orphan_tag: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/release.yaml

@@ -4,55 +4,39 @@ on:
   push:
     tags:
       - "v*"
+      - "!v*-(alpha|beta|rc).*"
 
 jobs:
   release:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-node@v2
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
       - run: npm i -g @apidevtools/swagger-cli@4
       - name: Bundle yaml spec
         run: "swagger-cli bundle ./beacon-node-oapi.yaml -r -t yaml -o ./deploy/beacon-node-oapi.yaml"
       - name: Bundle json spec
         run: "swagger-cli bundle ./beacon-node-oapi.yaml -r -t json -o ./deploy/beacon-node-oapi.json"
       - name: Create Release
         id: create_release
-        uses: actions/create-release@v1
+        uses: softprops/action-gh-release@v2
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # This token is provided by Actions, you do not need to create your own token
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         with:
-          tag_name: ${{ github.ref }}
-          release_name: ${{ github.ref }}
+          name: ${{ github.ref_name }}
+          tag_name: ${{ github.ref_name }}
           draft: false
           prerelease: false
-      - name: Upload Yaml Bundle
-        uses: actions/upload-release-asset@v1
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        with:
-          upload_url: ${{ steps.create_release.outputs.upload_url }}
-          asset_path: ./deploy/beacon-node-oapi.yaml
-          asset_name: beacon-node-oapi.yaml
-          asset_content_type: text/x-yaml
-      - name: Upload Json Bundle
-        uses: actions/upload-release-asset@v1
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        with:
-          upload_url: ${{ steps.create_release.outputs.upload_url }}
-          asset_path: ./deploy/beacon-node-oapi.json
-          asset_name: beacon-node-oapi.json
-          asset_content_type: application/json
+          files: |
+            ./deploy/beacon-node-oapi.yaml
+            ./deploy/beacon-node-oapi.json
+          fail_on_unmatched_files: true
       - name: Rollback Release
         if: failure()
-        uses: author/action-rollback@stable
+        uses: author/action-rollback@1.0.4
         with:
-          # Using a known release ID
-          id: ${{ steps.create_release.id }}
-          # Using a tag name
+          release_id: ${{ steps.create_release.outputs.id }}
           tag: ${{ github.ref }}
-          # Always delete} the tag, even if a release is not associated with it.
-          always_delete_tag: true
+          delete_orphan_tag: true
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/spellcheck.yml

@@ -1,11 +1,17 @@
 name: Spellcheck
-on: [push, pull_request, workflow_dispatch]
+
+on:
+  push:
+    branches:
+      - "master"
+  pull_request:
+  workflow_dispatch:
 
 jobs:
   build:
     name: Spellcheck
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@master
-    - uses: rojopolis/spellcheck-github-actions@0.29.0
-      name: Spellcheck
+      - uses: actions/checkout@v4
+      - uses: rojopolis/spellcheck-github-actions@0.40.0
+        name: Spellcheck

CHANGES.md

@@ -15,6 +15,7 @@ There are likely to be descriptions etc outside of the list below, but new query
 | [#448](https://github.com/ethereum/beacon-APIs/pull/448) `POST /eth/v2/beacon/pool/attestations` added              |                                                  |                                                  |                                                    |                                                 |                                           |
 | [#448](https://github.com/ethereum/beacon-APIs/pull/448) `GET /eth/v2/beacon/pool/attester_slashings` added         |                                                  |                                                  |                                                    |                                                 |                                           |
 | [#448](https://github.com/ethereum/beacon-APIs/pull/448) `POST /eth/v2/beacon/pool/attester_slashings` added        |                                                  |                                                  |                                                    |                                                 |                                           |
+| [#456](https://github.com/ethereum/beacon-APIs/pull/456) `POST /eth/v2/validator/aggregate_and_proofs` added        |                                                  |                                                  |                                                    |                                                 |                                           |
 
 
 The Following are no longer in the Standard API, removed since the latest version.

README.md

@@ -81,3 +81,9 @@ redocly lint beacon-node-oapi.yaml
 ```
          {url: "./releases/<tag>/beacon-node-oapi.json", name: "<tag>"},
 ```
+
+### Pre-releases
+
+To create a pre-release, simply push a new tag with the suffix `-alpha.x`. The CD will create a github release and upload the bundled spec files.
+
+Pre-releases will not be listed in `index.html` and are intended to allow early testing against the spec.

apis/beacon/states/validator_balances.yaml

@@ -79,7 +79,7 @@ post:
   description: |
     Returns filterable list of validators balances.
 
-    Balances will be returned for all indices or public key that match known validators. If an index or public key does not
+    Balances will be returned for all indices or public keys that match known validators. If an index or public key does not
     match any known validator, no balance will be returned but this will not cause an error. There are no guarantees for the
     returned data in terms of ordering; the index is returned for each balance, and can be used to confirm for which inputs a
     response has been returned.
@@ -90,7 +90,10 @@ post:
       in: path
       $ref: '../../../beacon-node-oapi.yaml#/components/parameters/StateId'
   requestBody:
-    description: "An array of either hex encoded public key (any bytes48 with 0x prefix) or validator index"
+    description: |
+      An array of values, with each value either a hex encoded public key (any bytes48 with 0x prefix) or a validator index.
+
+      If the supplied list is empty (i.e. the body is `[]`) or no body is supplied then balances will be returned for all validators.
     required: false
     content:
       application/json:

apis/node/health.yaml

@@ -17,7 +17,7 @@ get:
     "200":
       description: Node is ready
     "206":
-      description: Either the beacon node is syncing, or its execution node is optimistic, so data served may be incorrect
+      description: Either the beacon node is syncing, or its execution node is optimistic or offline, so data served may be incorrect
     "400":
       description: Invalid syncing status code
     "503":

apis/validator/aggregate_and_proofs.v2.yaml

@@ -0,0 +1,33 @@
+post:
+  operationId: "publishAggregateAndProofsV2"
+  summary: "Publish multiple aggregate and proofs"
+  description: "Verifies given aggregate and proofs and publishes them on appropriate gossipsub topic."
+  tags:
+    - ValidatorRequiredApi
+    - Validator
+  parameters:
+    - in: header
+      schema:
+        $ref: '../../beacon-node-oapi.yaml#/components/schemas/ConsensusVersion'
+      required: true
+      name: Eth-Consensus-Version
+      description: "Version of the aggregate and proofs being submitted."
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          anyOf:
+            - type: array
+              items:
+                $ref: '../../beacon-node-oapi.yaml#/components/schemas/SignedAggregateAndProof'
+            - type: array
+              items:
+                $ref: '../../beacon-node-oapi.yaml#/components/schemas/Electra.SignedAggregateAndProof'
+  responses:
+    "200":
+      description: "Successful response"
+    "400":
+      $ref: '../../beacon-node-oapi.yaml#/components/responses/InvalidRequest'
+    "500":
+      $ref: '../../beacon-node-oapi.yaml#/components/responses/InternalError'

apis/validator/aggregate_and_proofs.yaml

@@ -1,6 +1,7 @@
 post:
   operationId: "publishAggregateAndProofs"
   summary: "Publish multiple aggregate and proofs"
+  deprecated: true
   description: "Verifies given aggregate and proofs and publishes them on appropriate gossipsub topic."
   tags:
     - ValidatorRequiredApi

apis/validator/sync_committee_contribution.yaml

@@ -10,6 +10,9 @@ get:
     A 503 error must be returned if the block identified by the response
     `beacon_block_root` is optimistic (i.e. the sync committee contribution
     refers to a block that has not been fully verified by an execution engine).
+
+    A 404 error must be returned if no sync committee contribution is available
+    for the requested `beacon_block_root`.
   parameters:
     - name: slot
       in: query

beacon-node-oapi.yaml

@@ -196,6 +196,8 @@ paths:
     $ref: "./apis/validator/aggregate_attestation.v2.yaml"
   /eth/v1/validator/aggregate_and_proofs:
     $ref: "./apis/validator/aggregate_and_proofs.yaml"
+  /eth/v2/validator/aggregate_and_proofs:
+    $ref: "./apis/validator/aggregate_and_proofs.v2.yaml"
   /eth/v1/validator/beacon_committee_subscriptions:
     $ref: "./apis/validator/beacon_committee_subscriptions.yaml"
   /eth/v1/validator/sync_committee_subscriptions:
@@ -389,6 +391,8 @@ components:
       $ref: './types/electra/attestation.yaml#/Electra/Attestation'
     Electra.AttesterSlashing:
       $ref: './types/electra/attester_slashing.yaml#/Electra/AttesterSlashing'
+    Electra.SignedAggregateAndProof:
+      $ref: './types/electra/validator.yaml#/Electra/SignedAggregateAndProof'
     Node:
       $ref: './types/fork_choice.yaml#/Node'
     ExtraData:

types/electra/validator.yaml

@@ -0,0 +1,29 @@
+Electra:
+  AggregateAndProof:
+    allOf:
+      - $ref: '#/Electra/Aggregate'
+      - type: object
+        required: [selection_proof]
+        properties:
+          selection_proof:
+            $ref: '../primitive.yaml#/Signature'
+
+  Aggregate:
+    type: object
+    description: "The [`AggregateAndProof`](https://github.com/ethereum/consensus-specs/blob/v1.5.0-alpha.3/specs/electra/validator.md#aggregateandproof) without selection_proof"
+    required: [aggregator_index, aggregate]
+    properties:
+      aggregator_index:
+        $ref: '../primitive.yaml#/Uint64'
+      aggregate:
+        $ref: './attestation.yaml#/Electra/Attestation'
+
+  SignedAggregateAndProof:
+    type: object
+    description: "The [`SignedAggregateAndProof`](https://github.com/ethereum/consensus-specs/blob/v1.5.0-alpha.3/specs/electra/validator.md#signedaggregateandproof) object"
+    required: [message, signature]
+    properties:
+      message:
+        $ref: "#/Electra/AggregateAndProof"
+      signature:
+        $ref: "../primitive.yaml#/Signature"

wordlist.txt

@@ -23,6 +23,7 @@ MEV
 PayloadAttributesV
 Gwei
 prev
+pre
 ENR
 enr
 attnets