RPC daemon

Remote Procedure Call

Like any other Erigon component, the Remote Procedure Call (RPC) can run within the Erigon all-in-one client or as an independent process. Erigon's rpcdaemon runs in its own separate process. This has many advantages, including easier development, the ability to run multiple daemons at once, and the ability to run the daemon remotely. It is also possible to run the daemon locally (read-only) if both processes have access to the data folder.

Getting Started

The rpcdaemon gets built as part of the main Erigon build process, but you can build it directly with this command:

make rpcdaemon

Built-in RPC daemon

To enable RPC server as a built-in service in Erigon add the flags --http and --ws (sharing same port with http). For example:

./build/bin/erigon --internalcl --http.vhosts="*" --http.addr="0.0.0.0" --http.api=eth,web3,net,debug,trace,txpool

Warning: The above example is a convenient but insecure snippet to allow users to connect their wallet from any host. To have a secure connection it is recommended to utilize TLS Authentication.

This command run Erigon on a remote server allowing connection from any host, enabling http api for eth, web3, net etc. To connect a remote wallet use IP address of the remote machine on the RPC URL. Default port is 8545 e.g. http://123.123.123.123:8545.

Websocket

Erigon supports also WebSocket protocol, just add the flag --ws to enable the WS-RPC server (default: false) or --ws.compression to enable compression over WebSocket (default: false).

In order to specify websocket server listening port you can use the flag --ws.port (default: 8546)

GraphQL

GraphQL protocol is also supported, add flag --graphql.

RPC as a separate process

The RPC daemon can use:

• The local database, with Erigon running or on a snapshot of a database

• A remote database running on another machine.

Running Locally

Run rpcdaemon on the same computer along with Erigon. It's the default option because it uses Shared Memory access to Erigon's db, which is much faster than TCP access. Always provide the following options: - --datadir to specify where Erigon data are stored; by default /home/user/.local/share/erigon. - --private.api.addr to provide private api network address (default "127.0.0.1:9090")

./build/bin/erigon  --internalcl --private.api.addr=localhost:9090 --http=false
./build/bin/rpcdaemon --private.api.addr=localhost:9090 --http.vhosts="*" --http.addr="0.0.0.0" --http.api=eth,erigon,web3,net,debug,trace,txpool —-datadir=/home/admin/.local/share/erigon

With the above command it has also been specified which RPC namespaces to enable by --http.api flag.

Running Remotely

In some cases, it is useful to run Erigon nodes in a different network (for example, in a public cloud), but rpcdaemon locally. In this scenario the local machine requires no storing capacity and basic computing requirements.

Warning: To ensure the integrity of communication and access control to the Erigon node, TLS authentication is needed.

This works regardless of whether RPC daemon is on the same computer with Erigon, or on a different one. They use TPC socket connection to pass data between them. To use this mode, run Erigon in one terminal window.

To start rpcdaemon remotely - just don't set the --datadir flag:

./build/bin/erigon --internalcl --private.api.addr=localhost:9090 --http=false
./build/bin/rpcdaemon --private.api.addr=localhost:9090 --http.api=eth,erigon,web3,net,debug,trace,txpool

If the Erigon process is on one machine and RPC daemon is on another machine, use the private.api.addr option for Erigon and open port 9090:

./build/bin/erigon --internalcl --private.api.addr=0.0.0.0:9090 --http=false --http.vhosts="*" --http.addr="0.0.0.0"

On the other machine:

./build/bin/rpcdaemon --http.vhosts="*" --private.api.addr=123.123.123.123:9090 --http.api=eth,erigon,web3,net,debug,trace,txpool

For instance you can run also a number of different RPC daemon on different machines, attaching to the same Erigon process.

The daemon should respond with something like:

INFO [date-time] HTTP endpoint opened url=localhost:8545...

When running remotely, rpcdaemon by default maintains a state cache that is updated each time Erigon imports a new block. When the state cache is reasonably warm, it allows such a remote RPC daemon to execute queries related to the latest block (i.e. current state) with comparable performance to a local rpcdaemon (about 2x slower vs. 10x slower without state cache). Since there can be multiple such RPC daemons per Erigon node, it may scale well for some workloads that are heavy on current state queries.

Healthcheck

There are 2 options for running healtchecks, POST request, or GET request with custom headers. Both options are available at the /health endpoint.

POST request

If the health check is successful it returns 200 OK.

If the health check fails it returns 500 Internal Server Error.

Configuration of the health check is sent as POST body of the method.

{
"min_peer_count": <minimal number of the node peers>,
"known_block": <number_of_block_that_node_should_know>
}

Not adding a check disables that.

v`min_peer_count` -- checks for mimimum of healthy node peers. Requires net namespace to be listed in http.api.

known_block -- sets up the block that node has to know about. Requires eth namespace to be listed in http.api.

Example request http POST http://localhost:8545/health --raw '{"min_peer_count": 3, "known_block": "0x1F"}'

Example response:

{
"check_block": "HEALTHY",
"healthcheck_query": "HEALTHY",
"min_peer_count": "HEALTHY"
}

GET with headers

If the healthcheck is successful it will return a 200 status code.

If the healthcheck fails for any reason a status 500 will be returned. This is true if one of the criteria requested fails its check.

You can set any number of values on the X-ERIGON-HEALTHCHECK header. Ones that are not included are skipped in the checks.

Available Options:

• synced - will check if the node has completed syncing

• min_peer_count<count> - will check that the node has at least <count> many peers

• check_block<block> - will check that the node is at least ahead of the specified <block>

• max_seconds_behind<seconds> - will check that the node is no more than <seconds> behind from its latest block

Example Request:

curl --location --request GET 'http://localhost:8545/health' \
--header 'X-ERIGON-HEALTHCHECK: min_peer_count1' \
--header 'X-ERIGON-HEALTHCHECK: synced' \
--header 'X-ERIGON-HEALTHCHECK: max_seconds_behind600'

Example Response

{
"check_block":"DISABLED",
"max_seconds_behind":"HEALTHY",
"min_peer_count":"HEALTHY",
"synced":"HEALTHY"
}

Testing

By default, the rpcdaemon serves data from localhost:8545. You may send curl commands to see if things are working.

Try eth_blockNumber for example. In a third terminal window enter this command:

curl -X POST -H "Content-Type: application/json" --data '{"jsonrpc": "2.0", "method": "eth_blockNumber", "params": [], "id":1}' localhost:8545

This should return something along the lines of this (depending on how far your Erigon node has synced):

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

Postman may also be used to test rpcdaemon.

Command Line Options

RPCdaemon is started and controlled using the command line. It is stopped by pressing ctrl-c.

You can configure RPCdaemon using command-line options (a.k.a. flags), which you can use to specify also sub-commands to invoke other functionalities.

The command-line help listing is reproduced below for your convenience. The same information can be obtained at any time from your own RPCdaemon instance by running:

./build/bin/rpcdaemon --help

gRPC ports

9090 erigon, 9091 sentry, 9092 consensus engine, 9093 torrent downloader, 9094 transactions pool

Supported JSON-RPC calls (eth, debug , net, web3):

For a details on the implementation status of each command, see this table.

For more detailed on RPC daemon info refer to this page:

https://github.com/ledgerwatch/erigon/blob/main/cmd/rpcdaemon/README.md

Commands

rpcdaemon is JSON RPC server that connects to Erigon node for remote DB access

Usage:
  rpcdaemon [flags]

Flags:
      --datadir string                 path to Erigon working directory
      --db.read.concurrency int        Does limit amount of parallel db reads. Default: equal to GOMAXPROCS (or number of CPU) (default 192)
      --graphql                        enables graphql endpoint (disabled by default)
      --grpc                           Enable GRPC server
      --grpc.addr string               GRPC server listening interface (default "localhost")
      --grpc.healthcheck               Enable GRPC health check
      --grpc.port int                  GRPC server listening port (default 8547)
  -h, --help                           help for rpcdaemon
      --http.addr string               HTTP-RPC server listening interface (default "localhost")
      --http.api strings               API's offered over the HTTP-RPC interface: eth,erigon,web3,net,debug,trace,txpool,db. Supported methods: https://github.com/ledgerwatch/erigon/tree/devel/cmd/rpcdaemon (default [eth,erigon])
      --http.compression               Disable http compression (default true)
      --http.corsdomain strings        Comma separated list of domains from which to accept cross origin requests (browser enforced)
      --http.port int                  HTTP-RPC server listening port (default 8545)
      --http.timeouts.idle duration    Maximum amount of time to wait for the next request when keep-alives are enabled. If http.timeouts.idle is zero, the value of http.timeouts.read is used (default 2m0s)
      --http.timeouts.read duration    Maximum duration for reading the entire request, including the body. (default 30s)
      --http.timeouts.write duration   Maximum duration before timing out writes of the response. It is reset whenever a new request's header is read (default 30m0s)
      --http.trace                     Trace HTTP requests with INFO level
      --http.vhosts strings            Comma separated list of virtual hostnames from which to accept requests (server enforced). Accepts '*' wildcard. (default [localhost])
      --log.console.json               Format console logs with JSON
      --log.console.verbosity string   Set the log level for console logs (default "info")
      --log.dir.json                   Format file logs with JSON
      --log.dir.path string            Path to store user and error logs to disk
      --log.dir.prefix string          The file name prefix for logs stored to disk
      --log.dir.verbosity string       Set the log verbosity for logs stored to disk (default "info")
      --log.json                       Format console logs with JSON
      --metrics                        Enable metrics collection and reporting
      --metrics.addr string            Enable stand-alone metrics HTTP server listening interface (default "127.0.0.1")
      --metrics.port int               Metrics HTTP server listening port (default 6060)
      --pprof                          Enable the pprof HTTP server
      --pprof.addr string              pprof HTTP server listening interface (default "127.0.0.1")
      --pprof.cpuprofile string        Write CPU profile to the given file
      --pprof.port int                 pprof HTTP server listening port (default 6060)
      --private.api.addr string        Erigon's components (txpool, rpcdaemon, sentry, downloader, ...) can be deployed as independent Processes on same/another server. Then components will connect to erigon by this internal grpc API. Example: 127.0.0.1:9090 (default "127.0.0.1:9090")
      --rpc.accessList string          Specify granular (method-by-method) API allowlist
      --rpc.batch.concurrency uint     Does limit amount of goroutines to process 1 batch request. Means 1 bach request can't overload server. 1 batch still can have unlimited amount of request (default 2)
      --rpc.batch.limit int            Maximum number of requests in a batch (default 100)
      --rpc.evmtimeout duration        Maximum amount of time to wait for the answer from EVM call. (default 5m0s)
      --rpc.gascap uint                Sets a cap on gas that can be used in eth_call/estimateGas (default 50000000)
      --rpc.returndata.limit int       Maximum number of bytes returned from eth_call or similar invocations (default 100000)
      --rpc.streaming.disable          Erigon has enalbed json streaming for some heavy endpoints (like trace_*). It's treadoff: greatly reduce amount of RAM (in some cases from 30GB to 30mb), but it produce invalid json format if error happened in the middle of streaming (because json is not streaming-friendly format)
      --rpc.txfeecap float             Sets a cap on transaction fee (in ether) that can be sent via the RPC APIs (0 = no cap) (default 1)
      --snapshot                       Default: use snapshots "true" for Mainnet, Goerli, Gnosis Chain and Chiado. use snapshots "false" in all other cases (default true)
      --state.cache string             Amount of data to store in StateCache (enabled if no --datadir set). Set 0 to disable StateCache. Defaults to 0MB RAM (default "0MB")
      --tcp                            Enable TCP server
      --tcp.addr string                TCP server listening interface (default "localhost")
      --tcp.port int                   TCP server listening port (default 8548)
      --tls.cacert string              CA certificate for client side TLS handshake
      --tls.cert string                certificate for client side TLS handshake
      --tls.key string                 key file for client side TLS handshake
      --trace string                   Write execution trace to the given file
      --trace.compat                   Bug for bug compatibility with OE for trace_ routines
      --trace.maxtraces uint           Sets a limit on traces that can be returned in trace_filter (default 200)
      --txpool.api.addr string         txpool api network address, for example: 127.0.0.1:9090 (default: use value of --private.api.addr)
      --verbosity string               Set the log level for console logs (default "info")
      --ws                             Enable Websockets - Same port as HTTP
      --ws.compression                 Enable Websocket compression (RFC 7692)