From 6baad462f62b2a80404882f1dd9b31d5a9c2b059 Mon Sep 17 00:00:00 2001 From: tclemos Date: Tue, 1 Oct 2024 16:16:48 -0300 Subject: [PATCH] adds a tool to generate a markdown document with all implemented rpc endpoints --- docs/endpoints/Makefile | 13 +++ docs/endpoints/README.md | 19 ++++ docs/endpoints/endpoints.md | 200 ++++++++++++++++++++++++++++++++++++ docs/endpoints/main.go | 106 +++++++++++++++++++ docs/endpoints/template.md | 16 +++ 5 files changed, 354 insertions(+) create mode 100644 docs/endpoints/Makefile create mode 100644 docs/endpoints/README.md create mode 100644 docs/endpoints/endpoints.md create mode 100644 docs/endpoints/main.go create mode 100644 docs/endpoints/template.md diff --git a/docs/endpoints/Makefile b/docs/endpoints/Makefile new file mode 100644 index 00000000000..d9af1597ee3 --- /dev/null +++ b/docs/endpoints/Makefile @@ -0,0 +1,13 @@ +DOC_NAME:="endpoints.md" + +.PHONY: gen-doc +gen-doc: + go run main.go $(DOC_NAME) + +.PHONY: check-doc +check-doc: + go run main.go tmp$(DOC_NAME) + cmp -s ./$(DOC_NAME) ./tmp$(DOC_NAME); \ + RETVAL=$$?; \ + rm ./tmp$(DOC_NAME); \ + exit $$RETVAL \ No newline at end of file diff --git a/docs/endpoints/README.md b/docs/endpoints/README.md new file mode 100644 index 00000000000..e68b2f6a3bc --- /dev/null +++ b/docs/endpoints/README.md @@ -0,0 +1,19 @@ +# JSON RPC Endpoints + +This tool is used to generate the list of supported endpoints provided by the JSON-RPC server as a markdown document. + +It uses reflection to go through all API interfaces and then merge the information with the content of the [template.md](./template.md) as the base to generate the [endpoints.md](./endpoints.md) file. + +To generate the file ensure you have `make` and `go` installed, then run available on this directory: + +```bash +make gen-doc +``` + +The [endpoints.md](./endpoints.md) must always be generated when a new endpoint is added, removed or changed so we can have this file pushed to the repo for further use. + +There is also a command to check if the current file is compatible with the current code. This command is meant to be used in the CI do ensure the doc is updated. + +```bash +make check-doc +``` \ No newline at end of file diff --git a/docs/endpoints/endpoints.md b/docs/endpoints/endpoints.md new file mode 100644 index 00000000000..b6733ffa0d1 --- /dev/null +++ b/docs/endpoints/endpoints.md @@ -0,0 +1,200 @@ + + +# RPC Endpoints + +> DO NOT EDIT THIS FILE. +This document was auto generated by [./main.go](./main.go) based on the interfaces the JSON-RPC server use to expose the public endpoints +For more details read the [./README.md](./README.md) + +Here you will find the list of all supported JSON RPC endpoints. +If the endpoint is not in the list below, it means this specific endpoint is not supported yet, feel free to open an issue requesting it to be added and please explain the reason why you need it. + +## admin + +- admin_nodeInfo +- admin_peers + +## bor + +- bor_getAuthor +- bor_getCurrentProposer +- bor_getCurrentValidators +- bor_getRootHash +- bor_getSigners +- bor_getSignersAtHash +- bor_getSnapshot +- bor_getSnapshotAtHash + +## debug + +- debug_accountAt +- debug_accountRange +- debug_getModifiedAccountsByHash +- debug_getModifiedAccountsByNumber +- debug_storageRangeAt +- debug_traceBlockByHash +- debug_traceBlockByNumber +- debug_traceCall +- debug_traceTransaction +- debug_traceTransactionCounters + +## engine + +- engine_exchangeTransitionConfigurationV1 +- engine_forkchoiceUpdatedV1 +- engine_forkchoiceUpdatedV2 +- engine_getPayloadBodiesByHashV1 +- engine_getPayloadBodiesByRangeV1 +- engine_getPayloadV1 +- engine_getPayloadV2 +- engine_newPayloadV1 +- engine_newPayloadV2 + +## erigon + +- erigon_blockNumber +- erigon_cumulativeChainTraffic +- erigon_forks +- erigon_getBalanceChangesInBlock +- erigon_getBlockByTimestamp +- erigon_getBlockReceiptsByBlockHash +- erigon_getHeaderByHash +- erigon_getHeaderByNumber +- erigon_getLatestLogs +- erigon_getLogs +- erigon_getLogsByHash +- erigon_nodeInfo + +## eth + +- eth_accounts +- eth_blockNumber +- eth_call +- eth_chainId +- eth_coinbase +- eth_createAccessList +- eth_estimateGas +- eth_gasPrice +- eth_getBalance +- eth_getBlockByHash +- eth_getBlockByNumber +- eth_getBlockReceipts +- eth_getBlockTransactionCountByHash +- eth_getBlockTransactionCountByNumber +- eth_getCode +- eth_getFilterChanges +- eth_getFilterLogs +- eth_getLogs +- eth_getProof +- eth_getRawTransactionByBlockHashAndIndex +- eth_getRawTransactionByBlockNumberAndIndex +- eth_getRawTransactionByHash +- eth_getStorageAt +- eth_getTransactionByBlockHashAndIndex +- eth_getTransactionByBlockNumberAndIndex +- eth_getTransactionByHash +- eth_getTransactionCount +- eth_getTransactionReceipt +- eth_getUncleByBlockHashAndIndex +- eth_getUncleByBlockNumberAndIndex +- eth_getUncleCountByBlockHash +- eth_getUncleCountByBlockNumber +- eth_getWork +- eth_hashrate +- eth_mining +- eth_newBlockFilter +- eth_newFilter +- eth_newPendingTransactionFilter +- eth_protocolVersion +- eth_sendRawTransaction +- eth_sendTransaction +- eth_sign +- eth_signTransaction +- eth_submitHashrate +- eth_submitWork +- eth_syncing +- eth_uninstallFilter + +## graphql + +- graphql_getBlockDetails +- graphql_getChainID + +## net + +- net_listening +- net_peerCount +- net_version + +## otterscan + +- otterscan_getApiLevel +- otterscan_getBlockDetails +- otterscan_getBlockDetailsByHash +- otterscan_getBlockTransactions +- otterscan_getContractCreator +- otterscan_getInternalOperations +- otterscan_getTransactionBySenderAndNonce +- otterscan_getTransactionError +- otterscan_hasCode +- otterscan_searchTransactionsAfter +- otterscan_searchTransactionsBefore +- otterscan_traceTransaction + +## parity + +- parity_listStorageKeys + +## trace + +- trace_block +- trace_call +- trace_callMany +- trace_filter +- trace_get +- trace_rawTransaction +- trace_replayBlockTransactions +- trace_replayTransaction +- trace_transaction + +## txpool + +- txpool_content +- txpool_limbo + +## web3 + +- web3_clientVersion +- web3_sha3 + +## zkevm + +- zkevm_batchNumber +- zkevm_batchNumberByBlockNumber +- zkevm_consolidatedBlockNumber +- zkevm_estimateCounters +- zkevm_getBatchByNumber +- zkevm_getBatchCountersByNumber +- zkevm_getBatchWitness +- zkevm_getBlockRangeWitness +- zkevm_getExitRootTable +- zkevm_getExitRootsByGER +- zkevm_getForkById +- zkevm_getForkId +- zkevm_getForkIdByBatchNumber +- zkevm_getForks +- zkevm_getFullBlockByHash +- zkevm_getFullBlockByNumber +- zkevm_getL2BlockInfoTree +- zkevm_getLatestGlobalExitRoot +- zkevm_getProverInput +- zkevm_getVersionHistory +- zkevm_getWitness +- zkevm_isBlockConsolidated +- zkevm_isBlockVirtualized +- zkevm_verifiedBatchNumber +- zkevm_virtualBatchNumber diff --git a/docs/endpoints/main.go b/docs/endpoints/main.go new file mode 100644 index 00000000000..4acdd236d6a --- /dev/null +++ b/docs/endpoints/main.go @@ -0,0 +1,106 @@ +package main + +import ( + "fmt" + "os" + "reflect" + "sort" + "text/template" + "unicode" + "unicode/utf8" + + "github.com/ledgerwatch/erigon/cmd/rpcdaemon/commands" +) + +const disclaimer = `DO NOT EDIT THIS FILE. +This document was auto generated by [./main.go](./main.go) based on the interfaces the JSON-RPC server use to expose the public endpoints +For more details read the [./README.md](./README.md)` + +type Document struct { + Disclaimer string + EndpointGroups []keyValue +} + +type keyValue struct { + Key any + Value any +} + +func main() { + apiInterfaces := []keyValue{ + {"admin", (*commands.AdminAPI)(nil)}, + {"bor", (*commands.BorAPI)(nil)}, + {"debug", (*commands.PrivateDebugAPI)(nil)}, + {"engine", (*commands.EngineAPI)(nil)}, + {"erigon", (*commands.ErigonAPI)(nil)}, + {"eth", (*commands.EthAPI)(nil)}, + {"graphql", (*commands.GraphQLAPI)(nil)}, + {"net", (*commands.NetAPI)(nil)}, + {"otterscan", (*commands.OtterscanAPI)(nil)}, + {"parity", (*commands.ParityAPI)(nil)}, + {"trace", (*commands.TraceAPI)(nil)}, + {"txpool", (*commands.TxPoolAPI)(nil)}, + {"web3", (*commands.Web3API)(nil)}, + {"zkevm", (*commands.ZkEvmAPI)(nil)}, + } + + endpointGroups := []keyValue{} + for _, apiInterface := range apiInterfaces { + apiPrefix := apiInterface.Key + apiInterfaceType := apiInterface.Value + + apiEndpoints := []string{} + interfaceType := reflect.TypeOf(apiInterfaceType).Elem() + for methodIndex := 0; methodIndex < interfaceType.NumMethod(); methodIndex++ { + methodName := interfaceType.Method(methodIndex).Name + methodName = firstToLower(methodName) + endpointName := fmt.Sprintf("%s_%s", apiPrefix, methodName) + apiEndpoints = append(apiEndpoints, endpointName) + } + + sort.Slice(apiEndpoints, func(i, j int) bool { + return apiEndpoints[i] < apiEndpoints[j] + }) + endpointGroup := keyValue{Key: apiPrefix, Value: apiEndpoints} + + endpointGroups = append(endpointGroups, endpointGroup) + } + + fileName := "endpoints.md" + fmt.Println(os.Args) + if len(os.Args) > 1 { + fileName = os.Args[1] + } + + f, err := createOrOpen(fileName) + checkErr(err) + + t := template.Must(template.New("template.md").ParseFiles("template.md")) + err = t.Execute(f, Document{disclaimer, endpointGroups}) + checkErr(err) +} + +func checkErr(err error) { + if err != nil { + panic(err) + } +} + +func createOrOpen(name string) (*os.File, error) { + if _, err := os.Stat(name); err == nil { + os.Remove(name) + } + return os.Create(name) +} + +func firstToLower(s string) string { + r, size := utf8.DecodeRuneInString(s) + if r == utf8.RuneError && size <= 1 { + return s + } + lc := unicode.ToLower(r) + if r == lc { + return s + } + return string(lc) + s[size:] +} diff --git a/docs/endpoints/template.md b/docs/endpoints/template.md new file mode 100644 index 00000000000..9d371c17266 --- /dev/null +++ b/docs/endpoints/template.md @@ -0,0 +1,16 @@ + + +# RPC Endpoints + +> {{ .Disclaimer }} + +Here you will find the list of all supported JSON RPC endpoints. +If the endpoint is not in the list below, it means this specific endpoint is not supported yet, feel free to open an issue requesting it to be added and please explain the reason why you need it. +{{ range .EndpointGroups }} +## {{ .Key }} +{{ range .Value }} +- {{ . }} +{{- end }} +{{ end }} \ No newline at end of file