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 RPCDaemon
To enable RPC server as a built-in service in Erigon add the flags --http and --ws (sharing same port with http). For example:
Warning: The above example is a conveniente but insecure snipet to allow users to connect their wallet from any host. You can skip the
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).
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")
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:
For instance you can run also a number of different RPCDaemon 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"}'
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
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)