JSON-RPC over HTTP and WebSockets

To enable JSON-RPC over HTTP or WebSockets, use the --rpc-http-enabled and --rpc-ws-enabled options.

Geth console

The geth console is a REPL (Read, Evaluate, & Print Loop) JavaScript console. Use JSON-RPC APIs supported by geth and Hyperledger Besu directly in the console.

To use the geth console with Besu:

1. Start Besu with the --rpc-http-enabled option.
2. Specify which APIs to enable using the --rpc-http-api option.
3. Start the geth console specifying the JSON-RPC endpoint:

 geth attach http://localhost:8545

Use the geth console to call JSON-RPC API methods that geth and Besu share.

eth.syncing

JSON-RPC authentication

Besu disables Authentication by default.

HTTP and WebSocket requests

HTTP

To make RPC requests over HTTP, you can use curl.

curl -X POST --data '{"jsonrpc":"2.0","id":<request-ID>,"method":"<method-name>","params":[<method-parameters>]}' <JSON-RPC-http-endpoint:port>

curl -X POST --data '{"jsonrpc":"2.0","id":"1","method":"eth_blockNumber","params":[]}' http://127.0.0.1:8555

{
  "jsonrpc":"2.0",
  "id":"1",
  "result":"0x60e"
}

You can use curl to make multiple RPC requests over HTTP at the same time. Send the requests as an array, and receive an array of responses.

curl -X POST --data '[{"jsonrpc":"2.0","id":"1","method":"eth_blockNumber","params":[]}, {"jsonrpc":"2.0","id":"2","method":"admin_peers","params":[]}]' http://127.0.0.1:8555

[{
  "jsonrpc":"2.0",
  "id":"1",
  "result":"0x60e"
},{
  "jsonrpc":"2.0",
  "id":"2",
  "result":[]
}]

WebSockets

To make RPC requests over WebSockets, you can use wscat, a Node.js based command-line tool.

First connect to the WebSockets server using wscat (you only need to connect once per session):

wscat -c ws://<JSON-RPC-ws-endpoint:port>

After you establish a connection, the terminal displays a ‘>’ prompt. Send individual requests as a JSON data package at each prompt.

{"jsonrpc":"2.0","id":<request-ID>,"method":"<method-name>","params":[<method-parameters>]}

{"jsonrpc":"2.0","id":"1","method":"eth_blockNumber","params":[]}

{
  "jsonrpc":"2.0",
  "id":"1",
  "result":"0x23"
}

You can use wscat to make multiple RPC requests over WebSockets at the same time. Send the requests as an array, and receive an array of responses.

[{"jsonrpc":"2.0","id":"1","method":"eth_blockNumber","params":[]}, {"jsonrpc":"2.0","id":"2","method":"admin_peers","params":[]}]

[{
  "jsonrpc":"2.0",
  "id":"1",
  "result":"0x23"
},{
  "jsonrpc":"2.0",
  "id":"2",
  "result":[]
}]

Readiness and liveness endpoints

Besu provides readiness and liveness endpoints to confirm the Besu node status. Both return a 200 OK status when ready or live and a 503 Service Unavailable status if not ready or live.

Readiness

By default, the readiness check requires a connected peer and the node to be within two blocks of the best known block. If you have disabled P2P communication, you do not need peers. A live node with P2P disabled is always ready.

Use the query parameters minPeers and maxBlocksBehind to adjust the number of peers required and the number of blocks tolerance.

http://<JSON-RPC-HTTP-endpoint:port>/readiness

curl -v 'http://localhost:8545/readiness'

curl -v 'http://localhost:8545/readiness?minPeers=0&maxBlocksBehind=10'

Liveness

The liveness check requires the JSON-RPC server to be up.

http://<JSON-RPC-HTTP-endpoint:port>/liveness

curl -v 'http://localhost:8545/liveness'

API methods enabled by default

Besu enables the ETH, NET, and WEB3 API methods by default.

To enable the ADMIN, CLIQUE, DEBUG, EEA, IBFT, MINER, PERM, PLUGINS, PRIV, TRACE, and TXPOOL API methods, use the --rpc-http-api or --rpc-ws-api options.

Block parameter

When you make requests that might have different results depending on the block accessed, the block parameter specifies the block. Methods such as eth_getTransactionByBlockNumberAndIndex have a block parameter.

The block parameter can have the following values:

• blockNumber : quantity - The block number, specified in hexadecimal or decimal. 0 represents the genesis block.
• earliest : tag - The earliest (genesis) block.
• latest : tag - The last block mined.
• pending : tag - The last block mined plus pending transactions. Use only with eth_getTransactionCount.