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","method":"web3_clientVersion","params":[],"id":53}' <JSON-RPC-http-endpoint:port>

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","method":"web3_clientVersion","params":[],"id":53}

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.