diff --git a/.github/changes-template.md b/.github/changes-template.md new file mode 100644 index 00000000..86642624 --- /dev/null +++ b/.github/changes-template.md @@ -0,0 +1,13 @@ +## Development Version + +These endpoints have been added or updated since the last release. + +There are likely to be descriptions etc outside of the list below, but new query parameters, changes to headers, new endpoints should be listed. + +| Endpoint | [Lighthouse](https://github.com/sigp/lighthouse) | [Lodestar](https://github.com/ChainSafe/lodestar) | [Nimbus](https://github.com/status-im/nimbus-eth2) | [Prysm](https://github.com/prysmaticlabs/prysm) | [Teku](https://github.com/ConsenSys/teku) | +|---------------------------------------------------------------------------------------------------------------------|--------------------------------------------------|---------------------------------------------------|----------------------------------------------------|-------------------------------------------------|-------------------------------------------| + +The Following are no longer in the Standard API, removed since the latest version. + +| Endpoint | [Lighthouse](https://github.com/sigp/lighthouse) | [Lodestar](https://github.com/ChainSafe/lodestar) | [Nimbus](https://github.com/status-im/nimbus-eth2) | [Prysm](https://github.com/prysmaticlabs/prysm) | [Teku](https://github.com/ConsenSys/teku) | +|----------------------------------------------------------------------------------------------------------|--------------------------------------------------|---------------------------------------------------|----------------------------------------------------|-------------------------------------------------|-------------------------------------------| diff --git a/.github/workflows/deploy.yaml b/.github/workflows/deploy.yaml index c0c914da..2707a99f 100644 --- a/.github/workflows/deploy.yaml +++ b/.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 diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index c2b02cc2..a65fc0f3 100644 --- a/.github/workflows/main.yml +++ b/.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" diff --git a/.github/workflows/pre-release.yaml b/.github/workflows/pre-release.yaml new file mode 100644 index 00000000..969208de --- /dev/null +++ b/.github/workflows/pre-release.yaml @@ -0,0 +1,51 @@ +name: Pre-release + +on: + push: + tags: + - "v*-alpha.*" + - "v*-beta.*" + - "v*-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 }} diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml index eedf0e8a..9f31b1d5 100644 --- a/.github/workflows/release.yaml +++ b/.github/workflows/release.yaml @@ -4,55 +4,66 @@ on: push: tags: - "v*" + - "!v*-alpha.*" + - "!v*-beta.*" + - "!v*-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: 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: Update index.html + run: | + sed -i "/urls:/a \ {url: \"./releases/${{ github.ref_name }}/beacon-node-oapi.json\", name: \"${{ github.ref_name }}\"}," ./index.html + - name: Update Changelog + run: | + sed -i "s/## Development Version/## ${{ github.ref_name }}/" ./CHANGES.md + awk '/# Recent Changes/ {print; print ""; system("cat .github/changes-template.md"); next}1' CHANGES.md > temp && mv temp CHANGES.md + - name: Create Release Notes + run: | + echo "The following changes are included in this release:" > release-notes.md + awk '/^## ${{ github.ref_name }}/ {flag=1; next} /^## / {flag=0} flag { \ + if ($0 ~ /\| \[#/) {sub(/^\| /, "- "); sub(/\| .*$/, ""); sub(/[[:space:]]+$/, ""); print}}' CHANGES.md >> release-notes.md + - name: Create Pull Request + uses: peter-evans/create-pull-request@v6 + with: + token: ${{ secrets.GITHUB_TOKEN }} + commit-message: "Release ${{ github.ref_name }}" + branch: release-${{ github.ref_name }} + title: "Release ${{ github.ref_name }}" + body-path: "release-notes.md" + base: master + add-paths: index.html,CHANGES.md - 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 }} + body_path: "release-notes.md" 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 }} \ No newline at end of file + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.github/workflows/spellcheck.yml b/.github/workflows/spellcheck.yml index 3516f16f..52c49fdf 100644 --- a/.github/workflows/spellcheck.yml +++ b/.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 diff --git a/CHANGES.md b/CHANGES.md index b54ebc18..235c8c63 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -1,6 +1,5 @@ # Recent Changes - ## Development Version These endpoints have been added or updated since the last release. @@ -24,7 +23,7 @@ The Following are no longer in the Standard API, removed since the latest versio |----------------------------------------------------------------------------------------------------------|--------------------------------------------------|---------------------------------------------------|----------------------------------------------------|-------------------------------------------------|-------------------------------------------| -## Version 2.5.0 +## v2.5.0 These endpoints have been added or updated since the last release. @@ -41,7 +40,7 @@ There are likely to be descriptions etc outside of the list below, but new query | [#405](https://github.com/ethereum/beacon-APIs/pull/405) `block_gossip EVENT` added | | - | | | | -## Version 2.4.2 +## v2.4.2 These endpoints have been added or updated since the last release. @@ -53,7 +52,7 @@ There are likely to be descriptions etc outside of the list below, but new query | [#339](https://github.com/ethereum/beacon-APIs/pull/339) `POST /eth/v2/validator/*blocks` deprecated | | v1.14.0 | | | | -## Version 2.4.1 +## v2.4.1 | Endpoint | [Lighthouse](https://github.com/sigp/lighthouse) | [Lodestar](https://github.com/ChainSafe/lodestar) | [Nimbus](https://github.com/status-im/nimbus-eth2) | [Prysm](https://github.com/prysmaticlabs/prysm) | [Teku](https://github.com/ConsenSys/teku) | |---------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------|---------------------------------------------------|----------------------------------------------------|-------------------------------------------------|-------------------------------------------| @@ -70,7 +69,7 @@ There are likely to be descriptions etc outside of the list below, but new query | [#327](https://github.com/ethereum/beacon-APIs/pull/327) Increased maximum number of blobs from 4 to 6 | | v1.9.0 | | | | -## Version 2.4.0 +## v2.4.0 __Note__ Clients can add notes about level of support for specific endpoints if there are caveats or aspects not implemented. diff --git a/README.md b/README.md index df41a324..fb2454ab 100644 --- a/README.md +++ b/README.md @@ -68,16 +68,23 @@ redocly lint beacon-node-oapi.yaml ## Releasing -1. Create and push tag +This repository supports both stable and pre-releases. The version of the next release has to be +determined based on the changes in `master` branch since the last stable release. It is recommended +to create a pre-release before releasing a new stable version. - - Make sure `info.version` in `beacon-node-oapi.yaml` file is updated before tagging. This will need to be a PR, and will get the release process started. - - CD will create github release and upload bundled spec file +### Stable releases -2. Create a second PR, containing the updated `index.html`. Also change back the `info.version` in `beacon-node-api.yaml` back to `Dev` +Steps to create a new stable release: - - The `index.html` file needs a new release entrypoint added to refer to the new release. Find the `urls` field, - and add the new release as the first entry in the list. - Entry should be in following format(replace `` with real tag name from step 1.): -``` - {url: "./releases//beacon-node-oapi.json", name: ""}, -``` +- Create and push a tag with the version of the release, e.g. `v3.0.0` +- CD will create the github release, upload bundled spec files, and open a release PR +- Review, approve and merge the release PR to `master` branch + +### Pre-releases + +Steps to create a new pre-release: + +- Create and push a tag with the version of the release, e.g. `v3.0.0-alpha.0` +- CD will create the github release and upload bundled spec files + +Pre-releases will not be listed in `index.html` and are intended to allow early testing against the spec. diff --git a/apis/beacon/states/validator_balances.yaml b/apis/beacon/states/validator_balances.yaml index cf9ccf1e..aa0c3b7d 100644 --- a/apis/beacon/states/validator_balances.yaml +++ b/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: diff --git a/apis/node/health.yaml b/apis/node/health.yaml index 0aa363a7..e9c419e6 100644 --- a/apis/node/health.yaml +++ b/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": diff --git a/apis/validator/sync_committee_contribution.yaml b/apis/validator/sync_committee_contribution.yaml index 3aac4a21..53484bba 100644 --- a/apis/validator/sync_committee_contribution.yaml +++ b/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 diff --git a/wordlist.txt b/wordlist.txt index 35f7a54d..bfb27ac7 100644 --- a/wordlist.txt +++ b/wordlist.txt @@ -23,6 +23,7 @@ MEV PayloadAttributesV Gwei prev +pre ENR enr attnets