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). diff --git a/rpc/json-rpc-api.md b/rpc/json-rpc-api.md new file mode 100644 index 0000000000..64681afc39 --- /dev/null +++ b/rpc/json-rpc-api.md @@ -0,0 +1,158 @@ +## 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** | | +| admin_nodeInfo() | - | +| admin_peers() | - | +| admin_addPeer(url) | `String` | +| | | +| **Web3 API** | | +| web3_clientVersion() | - | +| web3_sha3(data) | `String` | +| | | +| **Network API** | | +| net_listening() | - | +| net_peerCount() | - | +| net_version() | - | +| | | +| **Ethereum API (Chain State)** | | +| eth_blockNumber() | - | +| eth_chainID/eth_chainId() | - | +| eth_protocolVersion() | - | +| eth_syncing() | - | +| eth_gasPrice() | - | +| eth_maxPriorityFeePerGas() | - | +| eth_feeHistory() | - | +| | | +| **Ethereum API (Blocks)** | | +| 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)** | | +| 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)** | | +| 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)** | | +| eth_newFilter(...) | `FilterOptions` | +| eth_newBlockFilter() | - | +| eth_newPendingTransactionFilter() | - | +| eth_getFilterLogs(...) | `FilterId` | +| eth_getFilterChanges(...) | `FilterId` | +| eth_uninstallFilter(...) | `FilterId` | +| eth_getLogs(...) | `FilterOptions` | +| | | +| **Ethereum API (Account 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)** | | +| eth_mining() | - | +| eth_coinbase() | - | +| eth_hashrate() | - | +| eth_submitHashrate(...) | `HashRate`, `ClientID` | +| eth_getWork() | - | +| eth_submitWork(...) | `Nonce`, `PowHash`, `Digest` | +| | | +| **Ethereum API (Pub/Sub)** | | +| eth_subscribe(...) | `String`, `Object` | +| eth_unsubscribe(...) | `SubscriptionId` | +| | | +| **Engine API** | | +| 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** | | +| 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** | | +| txpool_content() | - | +| txpool_contentFrom(...) | `Address` | +| txpool_status() | - | +| | | +| **BSC-Specific APIs** | | +| eth_getHeaderByNumber(...) | `BlockNumber\|Tag` with "finalized" | +| eth_getBlockByNumber(...) | `BlockNumber\|Tag` with "finalized", `Boolean` | +| eth_newFinalizedHeaderFilter() | - | +| eth_getFinalizedHeader(...) | `VerifiedValidatorNum` | +| eth_getFinalizedBlock(...) | `VerifiedValidatorNum`, `Boolean` | +| | | +| eth_getBlobSidecarByTxHash(...) | `TxHash`, `Boolean` | +| eth_getBlobSidecars(...) | `BlockNumber\|Tag\|BlockHash`, `Boolean` | +| | | +| 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. +