Implement JSON-RPC API namespace separation in documentation

docs/reference/json-rpc/debug-namespace.md

@@ -0,0 +1,13 @@
+---
+sidebar_position: 1
+---
+
+# Debug Namespace
+
+This page lists all JSON-RPC methods in the debug namespace.
+
+- [debug_getBadBlocks](/docs/reference/debug_getBadBlocks)
+- [debug_getRawBlock](/docs/reference/debug_getRawBlock)
+- [debug_getRawHeader](/docs/reference/debug_getRawHeader)
+- [debug_getRawReceipts](/docs/reference/debug_getRawReceipts)
+- [debug_getRawTransaction](/docs/reference/debug_getRawTransaction)

docs/reference/json-rpc/engine-namespace.md

@@ -0,0 +1,26 @@
+---
+sidebar_position: 1
+---
+
+# Engine Namespace
+
+This page lists all JSON-RPC methods in the engine namespace.
+
+- [engine_exchangeCapabilities](/docs/reference/engine_exchangeCapabilities)
+- [engine_exchangeTransitionConfigurationV1](/docs/reference/engine_exchangeTransitionConfigurationV1)
+- [engine_forkchoiceUpdatedV1](/docs/reference/engine_forkchoiceUpdatedV1)
+- [engine_forkchoiceUpdatedV2](/docs/reference/engine_forkchoiceUpdatedV2)
+- [engine_forkchoiceUpdatedV3](/docs/reference/engine_forkchoiceUpdatedV3)
+- [engine_getBlobsV1](/docs/reference/engine_getBlobsV1)
+- [engine_getBlobsV2](/docs/reference/engine_getBlobsV2)
+- [engine_getPayloadBodiesByHashV1](/docs/reference/engine_getPayloadBodiesByHashV1)
+- [engine_getPayloadBodiesByRangeV1](/docs/reference/engine_getPayloadBodiesByRangeV1)
+- [engine_getPayloadV1](/docs/reference/engine_getPayloadV1)
+- [engine_getPayloadV2](/docs/reference/engine_getPayloadV2)
+- [engine_getPayloadV3](/docs/reference/engine_getPayloadV3)
+- [engine_getPayloadV4](/docs/reference/engine_getPayloadV4)
+- [engine_getPayloadV5](/docs/reference/engine_getPayloadV5)
+- [engine_newPayloadV1](/docs/reference/engine_newPayloadV1)
+- [engine_newPayloadV2](/docs/reference/engine_newPayloadV2)
+- [engine_newPayloadV3](/docs/reference/engine_newPayloadV3)
+- [engine_newPayloadV4](/docs/reference/engine_newPayloadV4)

docs/reference/json-rpc/eth-namespace.md

@@ -0,0 +1,47 @@
+---
+sidebar_position: 1
+---
+
+# ETH Namespace
+
+This page lists all JSON-RPC methods in the eth namespace.
+
+- [eth_accounts](/docs/reference/eth_accounts)
+- [eth_blobBaseFee](/docs/reference/eth_blobBaseFee)
+- [eth_blockNumber](/docs/reference/eth_blockNumber)
+- [eth_call](/docs/reference/eth_call)
+- [eth_chainId](/docs/reference/eth_chainId)
+- [eth_coinbase](/docs/reference/eth_coinbase)
+- [eth_createAccessList](/docs/reference/eth_createAccessList)
+- [eth_estimateGas](/docs/reference/eth_estimateGas)
+- [eth_feeHistory](/docs/reference/eth_feeHistory)
+- [eth_gasPrice](/docs/reference/eth_gasPrice)
+- [eth_getBalance](/docs/reference/eth_getBalance)
+- [eth_getBlockByHash](/docs/reference/eth_getBlockByHash)
+- [eth_getBlockByNumber](/docs/reference/eth_getBlockByNumber)
+- [eth_getBlockReceipts](/docs/reference/eth_getBlockReceipts)
+- [eth_getBlockTransactionCountByHash](/docs/reference/eth_getBlockTransactionCountByHash)
+- [eth_getBlockTransactionCountByNumber](/docs/reference/eth_getBlockTransactionCountByNumber)
+- [eth_getCode](/docs/reference/eth_getCode)
+- [eth_getFilterChanges](/docs/reference/eth_getFilterChanges)
+- [eth_getFilterLogs](/docs/reference/eth_getFilterLogs)
+- [eth_getLogs](/docs/reference/eth_getLogs)
+- [eth_getProof](/docs/reference/eth_getProof)
+- [eth_getStorageAt](/docs/reference/eth_getStorageAt)
+- [eth_getTransactionByBlockHashAndIndex](/docs/reference/eth_getTransactionByBlockHashAndIndex)
+- [eth_getTransactionByBlockNumberAndIndex](/docs/reference/eth_getTransactionByBlockNumberAndIndex)
+- [eth_getTransactionByHash](/docs/reference/eth_getTransactionByHash)
+- [eth_getTransactionCount](/docs/reference/eth_getTransactionCount)
+- [eth_getTransactionReceipt](/docs/reference/eth_getTransactionReceipt)
+- [eth_getUncleCountByBlockHash](/docs/reference/eth_getUncleCountByBlockHash)
+- [eth_getUncleCountByBlockNumber](/docs/reference/eth_getUncleCountByBlockNumber)
+- [eth_maxPriorityFeePerGas](/docs/reference/eth_maxPriorityFeePerGas)
+- [eth_newBlockFilter](/docs/reference/eth_newBlockFilter)
+- [eth_newFilter](/docs/reference/eth_newFilter)
+- [eth_newPendingTransactionFilter](/docs/reference/eth_newPendingTransactionFilter)
+- [eth_sendRawTransaction](/docs/reference/eth_sendRawTransaction)
+- [eth_sendTransaction](/docs/reference/eth_sendTransaction)
+- [eth_sign](/docs/reference/eth_sign)
+- [eth_signTransaction](/docs/reference/eth_signTransaction)
+- [eth_syncing](/docs/reference/eth_syncing)
+- [eth_uninstallFilter](/docs/reference/eth_uninstallFilter)

docs/reference/json-rpc/introduction.md

@@ -0,0 +1,13 @@
+---
+sidebar_position: 1
+---
+
+# JSON-RPC API Introduction
+
+The Ethereum JSON-RPC API is organized into several namespaces, each containing related methods:
+
+- [Debug Namespace](/docs/reference/json-rpc/debug-namespace)
+- [Engine Namespace](/docs/reference/json-rpc/engine-namespace)
+- [Eth Namespace](/docs/reference/json-rpc/eth-namespace)
+
+Each namespace contains methods with specific functionality related to different aspects of Ethereum node operation.

method-namespaces.json

@@ -0,0 +1,64 @@
+{
+	"eth_getBlockByHash": "eth",
+	"eth_getBlockByNumber": "eth",
+	"eth_getBlockTransactionCountByHash": "eth",
+	"eth_getBlockTransactionCountByNumber": "eth",
+	"eth_getUncleCountByBlockHash": "eth",
+	"eth_getUncleCountByBlockNumber": "eth",
+	"eth_getBlockReceipts": "eth",
+	"eth_chainId": "eth",
+	"eth_syncing": "eth",
+	"eth_coinbase": "eth",
+	"eth_accounts": "eth",
+	"eth_blockNumber": "eth",
+	"eth_call": "eth",
+	"eth_estimateGas": "eth",
+	"eth_createAccessList": "eth",
+	"eth_gasPrice": "eth",
+	"eth_blobBaseFee": "eth",
+	"eth_maxPriorityFeePerGas": "eth",
+	"eth_feeHistory": "eth",
+	"eth_newFilter": "eth",
+	"eth_newBlockFilter": "eth",
+	"eth_newPendingTransactionFilter": "eth",
+	"eth_uninstallFilter": "eth",
+	"eth_getFilterChanges": "eth",
+	"eth_getFilterLogs": "eth",
+	"eth_getLogs": "eth",
+	"eth_sign": "eth",
+	"eth_signTransaction": "eth",
+	"eth_getBalance": "eth",
+	"eth_getStorageAt": "eth",
+	"eth_getTransactionCount": "eth",
+	"eth_getCode": "eth",
+	"eth_getProof": "eth",
+	"eth_sendTransaction": "eth",
+	"eth_sendRawTransaction": "eth",
+	"eth_getTransactionByHash": "eth",
+	"eth_getTransactionByBlockHashAndIndex": "eth",
+	"eth_getTransactionByBlockNumberAndIndex": "eth",
+	"eth_getTransactionReceipt": "eth",
+	"debug_getRawHeader": "debug",
+	"debug_getRawBlock": "debug",
+	"debug_getRawTransaction": "debug",
+	"debug_getRawReceipts": "debug",
+	"debug_getBadBlocks": "debug",
+	"engine_getBlobsV1": "engine",
+	"engine_getBlobsV2": "engine",
+	"engine_exchangeCapabilities": "engine",
+	"engine_forkchoiceUpdatedV1": "engine",
+	"engine_forkchoiceUpdatedV2": "engine",
+	"engine_forkchoiceUpdatedV3": "engine",
+	"engine_newPayloadV1": "engine",
+	"engine_newPayloadV2": "engine",
+	"engine_newPayloadV3": "engine",
+	"engine_newPayloadV4": "engine",
+	"engine_getPayloadV1": "engine",
+	"engine_getPayloadV2": "engine",
+	"engine_getPayloadV3": "engine",
+	"engine_getPayloadV4": "engine",
+	"engine_getPayloadV5": "engine",
+	"engine_getPayloadBodiesByHashV1": "engine",
+	"engine_getPayloadBodiesByRangeV1": "engine",
+	"engine_exchangeTransitionConfigurationV1": "engine"
+}

package.json

@@ -6,14 +6,15 @@
   "scripts": {
     "build": "npm run build:spec",
     "build:spec": "node scripts/build.mjs",
+    "build:namespaced-sidebars": "node scripts/generateNamespacedSidebars.mjs",
     "lint": "npm run build:spec && node scripts/validate.mjs && node scripts/graphql-validate.mjs",
     "clean": "rm -rf build && mkdir -p build",
     "generate-clients": "mkdir -p build && open-rpc-generator generate -c open-rpc-generator-config.json",
     "graphql:schema": "node scripts/graphql.mjs",
     "graphql:validate": "node scripts/graphql-validate.mjs",
     "docusaurus": "docusaurus",
-    "start:docs": "docusaurus start",
-    "build:docs": "docusaurus build",
+    "start:docs": "npm run build:spec && npm run build:namespaced-sidebars && docusaurus start",
+    "build:docs": "npm run build:spec && npm run build:namespaced-sidebars && docusaurus build",
     "swizzle:docs": "docusaurus swizzle",
     "deploy:docs": "docusaurus deploy",
     "clear:docs": "docusaurus clear",

scripts/build.mjs

@@ -18,12 +18,21 @@ function sortByMethodName(methods) {
 console.log("Loading files...\n");
 
 let methods = [];
+// Create a separate map for method namespaces
+let methodNamespaces = {};
+
 let methodsBase = "src/eth/";
 let methodFiles = fs.readdirSync(methodsBase);
 methodFiles.forEach(file => {
   console.log(file);
   let raw = fs.readFileSync(methodsBase + file);
   let parsed = yaml.load(raw);
+  // Store namespace mapping separately
+  parsed.forEach(method => {
+    if (method.name) {
+      methodNamespaces[method.name] = 'eth';
+    }
+  });
   methods = [
     ...methods,
     ...parsed,
@@ -36,6 +45,12 @@ methodFiles.forEach(file => {
   console.log(file);
   let raw = fs.readFileSync(methodsBase + file);
   let parsed = yaml.load(raw);
+  // Store namespace mapping separately
+  parsed.forEach(method => {
+    if (method.name) {
+      methodNamespaces[method.name] = 'debug';
+    }
+  });
   methods = [
     ...methods,
     ...parsed,
@@ -48,6 +63,12 @@ methodFiles.forEach(file => {
   console.log(file);
   let raw = fs.readFileSync(methodsBase + file);
   let parsed = yaml.load(raw);
+  // Store namespace mapping separately
+  parsed.forEach(method => {
+    if (method.name) {
+      methodNamespaces[method.name] = 'engine';
+    }
+  });
   methods = [
     ...methods,
     ...parsed,
@@ -98,6 +119,9 @@ const doc = {
 
 fs.writeFileSync('refs-openrpc.json', JSON.stringify(doc, null, '\t'));
 
+// Save the method namespace mapping separately
+fs.writeFileSync('method-namespaces.json', JSON.stringify(methodNamespaces, null, '\t'));
+
 let spec = await dereferenceDocument(doc);
 
 spec.components = {};

scripts/generateNamespacedSidebars.mjs

@@ -0,0 +1,93 @@
+import fs from 'fs';
+
+/**
+ * Generates a namespaced sidebar configuration based on the OpenRPC document
+ */
+async function generateNamespacedSidebars() {
+  console.log('Generating namespaced sidebars...');
+
+  // Read the OpenRPC document
+  const openrpcData = JSON.parse(fs.readFileSync('refs-openrpc.json', 'utf8'));
+
+  // Read the method namespaces mapping
+  const methodNamespaces = JSON.parse(fs.readFileSync('method-namespaces.json', 'utf8'));
+
+  // Group methods by namespace
+  const namespaces = {};
+
+  openrpcData.methods.forEach(method => {
+    const methodName = method.name;
+    const namespace = methodNamespaces[methodName] || extractNamespace(methodName);
+    if (!namespaces[namespace]) {
+      namespaces[namespace] = [];
+    }
+    namespaces[namespace].push(methodName);
+  });
+
+  // Make sure directory exists
+  if (!fs.existsSync('docs/reference/json-rpc')) {
+    fs.mkdirSync('docs/reference/json-rpc', { recursive: true });
+  }
+
+  // Add custom JSON-RPC reference sidebar to docs
+  fs.writeFileSync('docs/reference/json-rpc/eth-namespace.md', generateSidebarPage('ETH Namespace', namespaces['eth'] || []));
+  fs.writeFileSync('docs/reference/json-rpc/debug-namespace.md', generateSidebarPage('Debug Namespace', namespaces['debug'] || []));
+  fs.writeFileSync('docs/reference/json-rpc/engine-namespace.md', generateSidebarPage('Engine Namespace', namespaces['engine'] || []));
+
+  // Create a sidebar introduction page
+  fs.writeFileSync('docs/reference/json-rpc/introduction.md', generateIntroductionPage(Object.keys(namespaces)));
+
+  console.log('Namespaced sidebar files generated successfully!');
+}
+
+/**
+ * Extracts namespace from method name (e.g., eth_blockNumber -> eth)
+ */
+function extractNamespace(methodName) {
+  if (!methodName) return 'other';
+
+  const parts = methodName.split('_');
+  if (parts.length > 1) {
+    return parts[0];
+  }
+
+  return 'other';
+}
+
+/**
+ * Generates a markdown page for a specific namespace
+ */
+function generateSidebarPage(title, methods) {
+  const sortedMethods = [...methods].sort();
+
+  return `---
+sidebar_position: 1
+---
+
+# ${title}
+
+This page lists all JSON-RPC methods in the ${title.toLowerCase()}.
+
+${sortedMethods.map(method => `- [${method}](/docs/reference/${method})`).join('\n')}
+`;
+}
+
+/**
+ * Generates an introduction page for JSON-RPC API
+ */
+function generateIntroductionPage(namespaces) {
+  return `---
+sidebar_position: 1
+---
+
+# JSON-RPC API Introduction
+
+The Ethereum JSON-RPC API is organized into several namespaces, each containing related methods:
+
+${namespaces.map(namespace => `- [${namespace.charAt(0).toUpperCase() + namespace.slice(1)} Namespace](/docs/reference/json-rpc/${namespace}-namespace)`).join('\n')}
+
+Each namespace contains methods with specific functionality related to different aspects of Ethereum node operation.
+`;
+}
+
+generateNamespacedSidebars().catch(console.error);