Switch docs back to openrpc v2

.github/workflows/deploy.yaml

@@ -6,48 +6,29 @@ on:
       - main
   workflow_dispatch:
 
-jobs:
-  build:
-    name: Build Docusaurus
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 20
-          cache: npm
+env:
+  GITHUB_REPOSITORY: ${{ github.repository }}
 
-      - name: Install dependencies
-        run: npm install --frozen-lockfile
-
-      - name: Build specs and website
-        run: |
-          npm run build
-          npm run build:docs
-
-      - name: Upload Build Artifact
-        uses: actions/upload-pages-artifact@v3
-        with:
-          path: build
-
-  deploy:
-    name: Deploy to GitHub Pages
-    needs: build
-
-    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+jobs:
+  deploy-gh-pages:
     permissions:
-      pages: write # to deploy to Pages
-      id-token: write # to verify the deployment originates from an appropriate source
-
-    # Deploy to the github-pages environment
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
+      pages: write
+      id-token: write
+      contents: write
 
     runs-on: ubuntu-latest
     steps:
+      - uses: actions/checkout@v4
+      - name: Use Node.js 22
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+      - run: npm ci
+      - run: npm run build
+      - run: npm run build:docs
       - name: Deploy to GitHub Pages
-        id: deployment
-        uses: actions/deploy-pages@v4
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: build/docs/gatsby/public
+          commit_message: "Deploy to GitHub Pages"

.github/workflows/test-deploy.yaml

@@ -12,13 +12,16 @@ jobs:
   test-deploy:
     name: Test deployment
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [20, 22, 24]
     steps:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
       - uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: ${{ matrix.node-version }}
           cache: npm
 
       - name: Install dependencies

.github/workflows/test.yaml

@@ -6,11 +6,11 @@ jobs:
   lint-and-check:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
-      - name: Use Node.js 15.x
-        uses: actions/setup-node@v1
+      - uses: actions/checkout@v4
+      - name: Use Node.js 22
+        uses: actions/setup-node@v4
         with:
-          node-version: ^15.x
+          node-version: 22
       - run: npm ci
       - run: npm run build
       - run: npm run lint

.gitignore

@@ -7,4 +7,3 @@ data.json
 schema.json
 *.dic
 .idea/
-.docusaurus

README.md

@@ -11,10 +11,10 @@ Ethereum clients as modules that can be swapped at will.
 
 ### Contributing
 
-Please see the contributors guide in [`docs/making-changes.md`][making-changes]
+Please see the [contributors guide][contributors-guide]
 for general information about the process of standardizing new API methods and
 making changes to existing ones. Information on test generation can be found
-in [`tests/README.md`][test-gen]
+in [test-gen][test-gen]
 
 The specification itself is written in [OpenRPC][openrpc]. Refer to the OpenRPC
 specification and the JSON schema [specification][json-schema] to get started.
@@ -112,8 +112,8 @@ This repository is licensed under [CC0](LICENSE).
 [validator]: https://open-rpc.github.io/schema-utils-js/functions/validateOpenRPCDocument.html
 [graphql-schema]: http://graphql-schema.ethdevops.io/?url=https://github.com/ethereum/execution-apis/main/graphql.json
 [eip-1767]: https://eips.ethereum.org/EIPS/eip-1767
-[making-changes]: docs/making-changes.md
+[contributors-guide]: docs/reference/contributors-guide.md
 [json-schema]: https://json-schema.org
 [hive]: https://github.com/ethereum/hive
 [rpc-compat]: https://github.com/ethereum/hive/tree/master/simulators/ethereum/rpc-compat
-[test-gen]: tests/README.md
+[test-gen]: docs/reference/tests.md

docs/config/gatsby-config.js

@@ -0,0 +1,82 @@
+const remarkGfm = require('remark-gfm');
+
+module.exports = {
+  pathPrefix: "/execution-apis",
+  siteMetadata: {
+    title: 'Ethereum JSON-RPC Specification',
+    description: 'A specification of the standard interface for Ethereum clients.',
+    siteUrl: process.env.GITHUB_REPOSITORY 
+      ? `https://${process.env.GITHUB_REPOSITORY.split('/')[0]}.github.io/execution-apis`
+      : 'https://ethereum.github.io/execution-apis', // fallback for local development
+    logoUrl: 'https://github.com/open-rpc/design/master/icons/open-rpc-logo-noText/open-rpc-logo-noText%20(PNG)/256x256.png',
+    primaryColor: '#3f51b5', //material-ui primary color
+    secondaryColor: '#f50057', //material-ui secondary color
+    author: '',
+    menuLinks: [
+      { name: 'Introduction', link: '/intro' },
+      {
+        name: 'API Documentation',
+        link: '/api-documentation'
+      },
+      { name: 'Quickstart', link: '/quickstart' },
+      { name: 'Contributors Guide', link: '/contributors-guide' },
+      { name: 'Testing', link: '/tests'},
+      { name: 'Ethsimulatev1 notes', link: '/ethsimulatev1-notes' },
+    ],
+    footerLinks: [
+      {
+        name: 'OpenRPC',
+        link: 'https://open-rpc.org'
+      }
+    ]
+  },
+  plugins: [
+   {
+      resolve: 'gatsby-plugin-mdx',
+      options: {
+        extensions: ['.mdx', '.md'],
+        gatsbyRemarkPlugins: [
+          {
+            resolve: 'gatsby-remark-autolink-headers',
+            options: {
+              icon: false,
+            },
+          },
+        ],
+        mdxOptions: {
+          remarkPlugins: [remarkGfm],
+        },
+      },
+    },
+    "gatsby-openrpc-theme",
+    {
+      resolve: 'gatsby-plugin-manifest',
+      options: {
+        name: 'pristine-site',
+        short_name: 'pristine-site',
+        start_url: '/execution-apis/',
+        background_color: 'transparent',
+        theme_color: '#3f51b5',
+        display: 'minimal-ui',
+        icon: 'src/images/gatsby-icon.png', // This path is relative to the root of the site.
+      },
+    },
+    "gatsby-plugin-image",
+    "gatsby-plugin-sharp",
+    "gatsby-transformer-sharp",
+    {
+      resolve: "gatsby-source-filesystem",
+      options: {
+        name: "images",
+        path: __dirname + '/src/images',
+      },
+    },
+    {
+      resolve: "gatsby-source-filesystem",
+      options: {
+        name: "docs",
+        path: __dirname + '/../../../docs/reference',
+      },
+    },
+  ],
+}

docs/reference/making-changes.md → docs/reference/contributors-guide.md

@@ -115,4 +115,4 @@ others don't.
 
 [exec-apis]: https://github.com/ethereum/execution-apis
 [pm]: https://github.com/ethereum/pm
-[test-gen]: https://github.com/ethereum/execution-apis/blob/main/tests/README.md
+[test-gen]: https://github.com/ethereum/execution-apis/blob/main/tests/README.md

docs/ethsimulatev1-notes.md → docs/reference/ethsimulatev1-notes.mdx

@@ -32,6 +32,7 @@ Unlike `eth_call`, `eth_simulateV1`'s calls are conducted inside blocks. We don'
 
 ## Default values for transactions
 As eth_simulate is an extension to `eth_call` we want to enable the nice user experience that the user does not need to provide all required values for a transaction. We are assuming following defaults if the variable is not provided by the user:
+
 | parameter name | description |
 -----------------|-----------------------
 | type | `0x2` |

docs/reference/intro.md

@@ -1,7 +1,3 @@
----
-slug: /
-sidebar_position: 1
----
 
 # Introduction
 
@@ -40,4 +36,4 @@ Each category serves specific purposes and provides different functionalities fo
 
 ## Contributing
 
-We welcome contributions to improve this documentation. Please see our [Making Changes](/reference/making-changes) guide for more information on how to contribute. 
+We welcome contributions to improve this documentation. Please see our [Contributors Guide](/reference/contributors-guide) guide for more information on how to contribute. 

docs/reference/quickstart.md

@@ -0,0 +1,119 @@
+# Execution API Specification
+
+## JSON-RPC
+
+[View the spec][playground]
+
+The Ethereum JSON-RPC is a standard collection of methods that all execution
+clients implement. It is the canonical interface between users and the network.
+This interface allows downstream tooling and infrastructure to treat different
+Ethereum clients as modules that can be swapped at will.
+
+### Contributing
+
+Please see the [contributors guide][contributors-guide]
+for general information about the process of standardizing new API methods and
+making changes to existing ones. Information on test generation can be found
+in [test-gen][test-gen]
+
+The specification itself is written in [OpenRPC][openrpc]. Refer to the OpenRPC
+specification and the JSON schema [specification][json-schema] to get started.
+
+### Building
+
+The specification is split into multiple files to improve readability. The
+spec can be compiled into a single document as follows:
+
+```console
+$ npm install
+$ npm run build
+Build successful.
+```
+
+This will output the file `openrpc.json` in the root of the project. This file
+will have all schema `#ref`s resolved.
+
+#### Testing
+
+There are several mechanisms for testing specification contributions and client
+conformance.
+
+First is the [OpenRPC validator][validator]. It performs some basic syntactic
+checks on the generated specification.
+
+```console
+$ npm install
+$ npm run lint
+OpenRPC spec validated successfully.
+```
+
+Next is `speccheck`. This tool validates the test cases in the `tests`
+directory against the specification.
+
+```console
+$ go install github.com/lightclient/rpctestgen/cmd/speccheck@latest
+$ speccheck -v
+all passing.
+```
+
+If you get an error that says: `speccheck: command not found`,
+ make sure that the go binary is in your $PATH:
+
+```console
+$ export PATH=$HOME/go/bin:$PATH
+```
+
+The spell checker ensures the specification is free of spelling errors.
+
+```console
+$ pip install pyspelling
+$ pyspelling -c spellcheck.yaml
+Spelling check passed :)
+```
+
+pyspelling is a wrapper around either [Aspell](http://aspell.net/) or
+[Hunspell](https://hunspell.github.io/). You'll need to install
+one of those before running `pyspelling`.
+
+Finally, the test cases in the `tests/` directory may be run against individual
+execution client using the [`hive`] simulator [`rpc-compat`][rpc-compat].
+Please see the documentation in the aforementioned repositories for more
+information.
+
+## GraphQL
+
+[View the spec][graphql-schema]
+
+[EIP-1767][eip-1767] proposed a GraphQL schema for interacting with Ethereum clients. Since then Besu and Geth have implemented the interface. This repo contains a live specification to integrate changes to the protocol as well as other improvements into the GraphQL schema.
+
+### Generation
+
+The schema in this repo is generated by issuing a meta GraphQL query against a live node. This can be done as follows:
+
+```console
+$ npm run graphql:schema
+```
+
+### Testing
+
+A script is included in the source code which reads and validates the given schema to be a valid one. It is recommended to perform this check after modifying the schema by:
+
+```console
+$ npm run graphql:validate
+```
+
+## License
+
+This repository is licensed under [CC0](LICENSE).
+
+
+[playground]: https://ethereum.github.io/execution-apis/docs/reference/json-rpc-api
+[openrpc]: https://open-rpc.org
+[validator]: https://open-rpc.github.io/schema-utils-js/functions/validateOpenRPCDocument.html
+[graphql-schema]: http://graphql-schema.ethdevops.io/?url=https://github.com/ethereum/execution-apis/main/graphql.json
+[eip-1767]: https://eips.ethereum.org/EIPS/eip-1767
+[contributors-guide]: docs/reference/contributors-guide.md
+[json-schema]: https://json-schema.org
+[hive]: https://github.com/ethereum/hive
+[rpc-compat]: https://github.com/ethereum/hive/tree/master/simulators/ethereum/rpc-compat
+[test-gen]: docs/reference/tests.md