From 1ddda813a5aea8b4914218c436c23ce25b04f440 Mon Sep 17 00:00:00 2001 From: qybdyx Date: Tue, 22 Apr 2025 12:05:15 +0800 Subject: [PATCH 1/4] feat: add json rpc docs --- rpc/json-rpc-api.md | 180 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 180 insertions(+) create mode 100644 rpc/json-rpc-api.md diff --git a/rpc/json-rpc-api.md b/rpc/json-rpc-api.md new file mode 100644 index 0000000000..9966902d68 --- /dev/null +++ b/rpc/json-rpc-api.md @@ -0,0 +1,180 @@ +## RPC API Reference + +This document provides a comprehensive list of JSON-RPC API methods supported. Each API is listed with its required parameters and their formats. + +### API Categories + +| Command | Parameters | +|-------------------------------------------------|--------------------------------------------------| +| **Admin API** | | +| *Node administration functions* | | +| admin_nodeInfo() | - | +| admin_peers() | - | +| admin_addPeer(url) | `String` | +| | | +| **Web3 API** | | +| *Basic web3 utility functions* | | +| web3_clientVersion() | - | +| web3_sha3(data) | `String` | +| | | +| **Network API** | | +| *Network status information* | | +| net_listening() | - | +| net_peerCount() | - | +| net_version() | - | +| | | +| **Ethereum API (Chain State)** | | +| *Blockchain state information* | | +| eth_blockNumber() | - | +| eth_chainID/eth_chainId() | - | +| eth_protocolVersion() | - | +| eth_syncing() | - | +| eth_gasPrice() | - | +| eth_maxPriorityFeePerGas() | - | +| eth_feeHistory() | - | +| | | +| **Ethereum API (Blocks)** | | +| *Block information and retrieval* | | +| eth_getBlockByHash(...) | `BlockHash`, `Boolean` | +| eth_getBlockByNumber(...) | `BlockNumber\|Tag`, `Boolean` | +| eth_getBlockTransactionCountByHash(...) | `BlockHash` | +| eth_getBlockTransactionCountByNumber(...) | `BlockNumber\|Tag` | +| eth_getUncleByBlockHashAndIndex(...) | `BlockHash`, `Integer` | +| eth_getUncleByBlockNumberAndIndex(...) | `BlockNumber\|Tag`, `Integer` | +| eth_getUncleCountByBlockHash(...) | `BlockHash` | +| eth_getUncleCountByBlockNumber(...) | `BlockNumber\|Tag` | +| | | +| **Ethereum API (Transactions)** | | +| *Transaction information and retrieval* | | +| eth_getTransactionByHash(...) | `TxHash` | +| eth_getRawTransactionByHash(...) | `TxHash` | +| eth_getTransactionByBlockHashAndIndex(...) | `BlockHash`, `Integer` | +| eth_retRawTransactionByBlockHashAndIndex(...) | `BlockHash`, `Integer` | +| eth_getTransactionByBlockNumberAndIndex(...) | `BlockNumber\|Tag`, `Integer` | +| eth_retRawTransactionByBlockNumberAndIndex(...) | `BlockNumber\|Tag`, `Integer` | +| eth_getTransactionReceipt(...) | `TxHash` | +| eth_getBlockReceipts(...) | `BlockNumber\|Tag` | +| | | +| **Ethereum API (State Reading)** | | +| *Reading contract and account state* | | +| eth_estimateGas(...) | `TxCallObject`, `BlockNumber\|Tag` | +| eth_getBalance(...) | `Address`, `BlockNumber\|Tag` | +| eth_getCode(...) | `Address`, `BlockNumber\|Tag` | +| eth_getTransactionCount(...) | `Address`, `BlockNumber\|Tag` | +| eth_getStorageAt(...) | `Address`, `Integer`, `BlockNumber\|Tag` | +| eth_call(...) | `TxCallObject`, `BlockNumber\|Tag` | +| eth_callMany(...) | `Array`, `BlockNumber\|Tag` | +| eth_callBundle(...) | `Array`, `BlockNumber\|Tag` | +| eth_createAccessList(...) | `TxCallObject`, `BlockNumber\|Tag` | +| | | +| **Ethereum API (Filters)** | | +| *Event filtering and subscriptions* | | +| eth_newFilter(...) | `FilterOptions` | +| eth_newBlockFilter() | - | +| eth_newPendingTransactionFilter() | - | +| eth_getFilterLogs(...) | `FilterId` | +| eth_getFilterChanges(...) | `FilterId` | +| eth_uninstallFilter(...) | `FilterId` | +| eth_getLogs(...) | `FilterOptions` | +| | | +| **Ethereum API (Account Operations)** | | +| *Account-related operations* | | +| eth_accounts() | - | +| eth_sendRawTransaction(...) | `SignedTxData` | +| eth_sendTransaction(...) | `TransactionObject` | +| eth_signTransaction(...) | `TransactionObject` | +| eth_signTypedData(...) | `Address`, `TypedData` | +| eth_getProof(...) | `Address`, `Array`, | +| | `BlockNumber\|Tag` | +| | | +| **Ethereum API (Mining)** | | +| *Mining-related operations* | | +| eth_mining() | - | +| eth_coinbase() | - | +| eth_hashrate() | - | +| eth_submitHashrate(...) | `HashRate`, `ClientID` | +| eth_getWork() | - | +| eth_submitWork(...) | `Nonce`, `PowHash`, `Digest` | +| | | +| **Ethereum API (Pub/Sub)** | | +| *Real-time event subscriptions* | | +| eth_subscribe(...) | `String`, `Object` | +| eth_unsubscribe(...) | `SubscriptionId` | +| | | +| **Engine API** | | +| *Execution layer consensus engine interface* | | +| engine_newPayloadV1(...) | `ExecutionPayloadV1` | +| engine_newPayloadV2(...) | `ExecutionPayloadV2` | +| engine_newPayloadV3(...) | `ExecutionPayloadV3` | +| engine_forkchoiceUpdatedV1(...) | `ForkchoiceState`, `PayloadAttributes` | +| engine_forkchoiceUpdatedV2(...) | `ForkchoiceState`, `PayloadAttributes` | +| engine_forkchoiceUpdatedV3(...) | `ForkchoiceState`, `PayloadAttributes` | +| engine_getPayloadV1(...) | `PayloadId` | +| engine_getPayloadV2(...) | `PayloadId` | +| engine_getPayloadV3(...) | `PayloadId` | +| | | +| **Debug API** | | +| *Debugging and trace functions* | | +| debug_getRawReceipts(...) | `BlockNumber\|Tag` | +| debug_accountRange(...) | `BlockNumber\|Tag`, `AccountKey`, `Integer`, `Boolean` | +| debug_accountAt(...) | `BlockNumber\|Tag`, `AccountIndex` | +| debug_getModifiedAccountsByNumber(...) | `StartBlock`, `EndBlock` | +| debug_getModifiedAccountsByHash(...) | `StartHash`, `EndHash` | +| debug_storageRangeAt(...) | `BlockHash`, `TxIndex`, `Address`, `StartKey`, `Integer` | +| debug_traceBlockByHash(...) | `BlockHash`, `TraceConfig` | +| debug_traceBlockByNumber(...) | `BlockNumber\|Tag`, `TraceConfig` | +| debug_traceTransaction(...) | `TxHash`, `TraceConfig` | +| debug_traceCall(...) | `TxCallObject`, `BlockNumber\|Tag`, `TraceConfig`| +| debug_traceCallMany(...) | `Array`, `BlockNumber\|Tag`, `TraceConfig` | +| | | +| **Transaction Pool API** | | +| *Pending transaction information* | | +| txpool_content() | - | +| txpool_contentFrom(...) | `Address` | +| txpool_status() | - | +| | | +| **BSC-Specific APIs** | | +| *APIs exclusive to BSC chain* | | +| **BSC Finality API** | | +| *Block finality verification and confirmation* | | +| eth_getHeaderByNumber(...) | `BlockNumber\|Tag` with "finalized" | +| eth_getBlockByNumber(...) | `BlockNumber\|Tag` with "finalized", `Boolean` | +| eth_newFinalizedHeaderFilter() | - | +| eth_getFinalizedHeader(...) | `VerifiedValidatorNum` | +| eth_getFinalizedBlock(...) | `VerifiedValidatorNum`, `Boolean` | +| | | +| **BSC Blob API** | | +| *Binary Large Object data retrieval* | | +| eth_getBlobSidecarByTxHash(...) | `TxHash`, `Boolean` | +| eth_getBlobSidecars(...) | `BlockNumber\|Tag\|BlockHash`, `Boolean` | +| | | +| **Other BSC-Specific APIs** | | +| *Additional BSC-only functionality* | | +| eth_health() | - | +| eth_getTransactionsByBlockNumber(...) | `BlockNumber\|Tag` | +| eth_getTransactionDataAndReceipt(...) | `TxHash` | +| | | + +### Parameter Types + +- `BlockNumber` - Hexadecimal block number +- `Tag` - String tag like "latest", "earliest", "pending", "safe", "finalized" +- `BlockHash` - 32-byte hash of a block +- `TxHash` - 32-byte hash of a transaction +- `Address` - 20-byte Ethereum address +- `Boolean` - true or false +- `Integer` - Numeric value +- `String` - Text string +- `TxCallObject` - Transaction call object with from/to/gas/value/data +- `FilterOptions` - Options for event filtering +- `FilterId` - ID of a previously created filter +- `VerifiedValidatorNum` - Number of validators that must verify a block +- `TraceConfig` - Configuration options for tracing + +### Notes + +- Methods that show (...) have parameters that were simplified for readability. +- APIs marked with "BSC-Specific" are only available on BSC nodes. +- Parameters in backticks (`) represent the expected data type. +- Some methods accept multiple parameter formats; consult detailed documentation for complete usage. + From 81f04a24689801d9ef3cbdf0b8ed3c03e3b63554 Mon Sep 17 00:00:00 2001 From: qybdyx Date: Tue, 22 Apr 2025 14:35:24 +0800 Subject: [PATCH 2/4] feat: update readme.md --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 54905b2834..5915fc4548 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ The goal of BNB Smart Chain is to bring programmability and interoperability to BNB Beacon Chain. In order to embrace the existing popular community and advanced technology, it will bring huge benefits by staying compatible with all the existing smart contracts on Ethereum and Ethereum tooling. And to achieve that, the easiest solution is to develop based on go-ethereum fork, as we respect the great work of Ethereum very much. -BNB Smart Chain starts its development based on go-ethereum fork. So you may see many toolings, binaries and also docs are based on Ethereum ones, such as the name “geth”. +BNB Smart Chain starts its development based on go-ethereum fork. So you may see many toolings, binaries and also docs are based on Ethereum ones, such as the name "geth". [![API Reference]( https://pkg.go.dev/badge/github.com/ethereum/go-ethereum @@ -194,8 +194,8 @@ $ geth --your-favourite-flags dumpconfig As a developer, sooner rather than later you'll want to start interacting with `geth` and the BSC network via your own programs and not manually through the console. To aid -this, `geth` has built-in support for a JSON-RPC based APIs ([standard APIs](https://ethereum.github.io/execution-apis/api-documentation/) -and [`geth` specific APIs](https://geth.ethereum.org/docs/interacting-with-geth/rpc)). +this, `geth` has built-in support for a JSON-RPC based APIs ([standard APIs](https://ethereum.github.io/execution-apis/api-documentation/), +[`geth` specific APIs](https://geth.ethereum.org/docs/interacting-with-geth/rpc), and [BSC's JSON-RPC API Reference](rpc/json-rpc-api.md)). These can be exposed via HTTP, WebSockets and IPC (UNIX sockets on UNIX based platforms, and named pipes on Windows). From 80675677658df252c6fa21a8f422e9da179e9c9a Mon Sep 17 00:00:00 2001 From: qybdyx Date: Tue, 22 Apr 2025 16:37:16 +0800 Subject: [PATCH 3/4] json-rpc-api.md: update docs --- rpc/json-rpc-api.md | 21 --------------------- 1 file changed, 21 deletions(-) diff --git a/rpc/json-rpc-api.md b/rpc/json-rpc-api.md index 9966902d68..6a8fe9bf34 100644 --- a/rpc/json-rpc-api.md +++ b/rpc/json-rpc-api.md @@ -7,24 +7,20 @@ This document provides a comprehensive list of JSON-RPC API methods supported. E | Command | Parameters | |-------------------------------------------------|--------------------------------------------------| | **Admin API** | | -| *Node administration functions* | | | admin_nodeInfo() | - | | admin_peers() | - | | admin_addPeer(url) | `String` | | | | | **Web3 API** | | -| *Basic web3 utility functions* | | | web3_clientVersion() | - | | web3_sha3(data) | `String` | | | | | **Network API** | | -| *Network status information* | | | net_listening() | - | | net_peerCount() | - | | net_version() | - | | | | | **Ethereum API (Chain State)** | | -| *Blockchain state information* | | | eth_blockNumber() | - | | eth_chainID/eth_chainId() | - | | eth_protocolVersion() | - | @@ -34,7 +30,6 @@ This document provides a comprehensive list of JSON-RPC API methods supported. E | eth_feeHistory() | - | | | | | **Ethereum API (Blocks)** | | -| *Block information and retrieval* | | | eth_getBlockByHash(...) | `BlockHash`, `Boolean` | | eth_getBlockByNumber(...) | `BlockNumber\|Tag`, `Boolean` | | eth_getBlockTransactionCountByHash(...) | `BlockHash` | @@ -45,7 +40,6 @@ This document provides a comprehensive list of JSON-RPC API methods supported. E | eth_getUncleCountByBlockNumber(...) | `BlockNumber\|Tag` | | | | | **Ethereum API (Transactions)** | | -| *Transaction information and retrieval* | | | eth_getTransactionByHash(...) | `TxHash` | | eth_getRawTransactionByHash(...) | `TxHash` | | eth_getTransactionByBlockHashAndIndex(...) | `BlockHash`, `Integer` | @@ -56,7 +50,6 @@ This document provides a comprehensive list of JSON-RPC API methods supported. E | eth_getBlockReceipts(...) | `BlockNumber\|Tag` | | | | | **Ethereum API (State Reading)** | | -| *Reading contract and account state* | | | eth_estimateGas(...) | `TxCallObject`, `BlockNumber\|Tag` | | eth_getBalance(...) | `Address`, `BlockNumber\|Tag` | | eth_getCode(...) | `Address`, `BlockNumber\|Tag` | @@ -68,7 +61,6 @@ This document provides a comprehensive list of JSON-RPC API methods supported. E | eth_createAccessList(...) | `TxCallObject`, `BlockNumber\|Tag` | | | | | **Ethereum API (Filters)** | | -| *Event filtering and subscriptions* | | | eth_newFilter(...) | `FilterOptions` | | eth_newBlockFilter() | - | | eth_newPendingTransactionFilter() | - | @@ -78,7 +70,6 @@ This document provides a comprehensive list of JSON-RPC API methods supported. E | eth_getLogs(...) | `FilterOptions` | | | | | **Ethereum API (Account Operations)** | | -| *Account-related operations* | | | eth_accounts() | - | | eth_sendRawTransaction(...) | `SignedTxData` | | eth_sendTransaction(...) | `TransactionObject` | @@ -88,7 +79,6 @@ This document provides a comprehensive list of JSON-RPC API methods supported. E | | `BlockNumber\|Tag` | | | | | **Ethereum API (Mining)** | | -| *Mining-related operations* | | | eth_mining() | - | | eth_coinbase() | - | | eth_hashrate() | - | @@ -97,12 +87,10 @@ This document provides a comprehensive list of JSON-RPC API methods supported. E | eth_submitWork(...) | `Nonce`, `PowHash`, `Digest` | | | | | **Ethereum API (Pub/Sub)** | | -| *Real-time event subscriptions* | | | eth_subscribe(...) | `String`, `Object` | | eth_unsubscribe(...) | `SubscriptionId` | | | | | **Engine API** | | -| *Execution layer consensus engine interface* | | | engine_newPayloadV1(...) | `ExecutionPayloadV1` | | engine_newPayloadV2(...) | `ExecutionPayloadV2` | | engine_newPayloadV3(...) | `ExecutionPayloadV3` | @@ -114,7 +102,6 @@ This document provides a comprehensive list of JSON-RPC API methods supported. E | engine_getPayloadV3(...) | `PayloadId` | | | | | **Debug API** | | -| *Debugging and trace functions* | | | debug_getRawReceipts(...) | `BlockNumber\|Tag` | | debug_accountRange(...) | `BlockNumber\|Tag`, `AccountKey`, `Integer`, `Boolean` | | debug_accountAt(...) | `BlockNumber\|Tag`, `AccountIndex` | @@ -128,28 +115,20 @@ This document provides a comprehensive list of JSON-RPC API methods supported. E | debug_traceCallMany(...) | `Array`, `BlockNumber\|Tag`, `TraceConfig` | | | | | **Transaction Pool API** | | -| *Pending transaction information* | | | txpool_content() | - | | txpool_contentFrom(...) | `Address` | | txpool_status() | - | | | | | **BSC-Specific APIs** | | -| *APIs exclusive to BSC chain* | | -| **BSC Finality API** | | -| *Block finality verification and confirmation* | | | eth_getHeaderByNumber(...) | `BlockNumber\|Tag` with "finalized" | | eth_getBlockByNumber(...) | `BlockNumber\|Tag` with "finalized", `Boolean` | | eth_newFinalizedHeaderFilter() | - | | eth_getFinalizedHeader(...) | `VerifiedValidatorNum` | | eth_getFinalizedBlock(...) | `VerifiedValidatorNum`, `Boolean` | | | | -| **BSC Blob API** | | -| *Binary Large Object data retrieval* | | | eth_getBlobSidecarByTxHash(...) | `TxHash`, `Boolean` | | eth_getBlobSidecars(...) | `BlockNumber\|Tag\|BlockHash`, `Boolean` | | | | -| **Other BSC-Specific APIs** | | -| *Additional BSC-only functionality* | | | eth_health() | - | | eth_getTransactionsByBlockNumber(...) | `BlockNumber\|Tag` | | eth_getTransactionDataAndReceipt(...) | `TxHash` | From f37f33ccdf7aa540a2e19cd722bb8802256d3faa Mon Sep 17 00:00:00 2001 From: qybdyx Date: Tue, 22 Apr 2025 16:42:12 +0800 Subject: [PATCH 4/4] json-rpc-api.md: update docs --- rpc/json-rpc-api.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/rpc/json-rpc-api.md b/rpc/json-rpc-api.md index 6a8fe9bf34..64681afc39 100644 --- a/rpc/json-rpc-api.md +++ b/rpc/json-rpc-api.md @@ -75,8 +75,7 @@ This document provides a comprehensive list of JSON-RPC API methods supported. E | eth_sendTransaction(...) | `TransactionObject` | | eth_signTransaction(...) | `TransactionObject` | | eth_signTypedData(...) | `Address`, `TypedData` | -| eth_getProof(...) | `Address`, `Array`, | -| | `BlockNumber\|Tag` | +| eth_getProof(...) | `Address`, `Array`,`BlockNumber\|Tag`| | | | | **Ethereum API (Mining)** | | | eth_mining() | - |