RPC server

Overview

Old Faithful ships with an RPC server that supports gRPC and JSON-RPC.

Command line

The RPC server is available via the faithful-cli rpc command.

The command accepts a list of epoch config files and dirs as arguments. Each config file is specific for an epoch and provides the location of the block/transaction data and the indexes for that epoch. The indexes are used to map Solana block numbers, transaction signatures, and addresses to their respective CIDs. The indexes are generated from the CAR file and can be generated via the faithful-cli index command (see Index generation).

It supports the following flags:

• --listen: The address to listen on, e.g. --listen=:8888

• --include: You can specify one or more (reuse the same flag multiple times) glob patterns to include files or dirs that match them, e.g. --include=/path/epoch-*.yml.

• --exclude: You can specify one or more (reuse the same flag multiple times) glob patterns to exclude files or dirs that match them, e.g. --exclude=/something-*/epoch-*.yml.

• --debug: Enable debug logging.

• --proxy: Proxy requests to a downstream RPC server if the data can't be found in the archive, e.g. --proxy=/path/to/my-rpc.json. See RPC server proxying for more details.

• --gsfa-only-signatures: When enabled, the RPC server will only return signatures for getSignaturesForAddress requests instead of the full transaction data.

• --watch: When specified, all the provided epoch files and dirs will be watched for changes, and the RPC server will automatically reload the data when changes are detected. Usage: --watch (boolean flag). This is useful when you want to provide just a folder and add new epochs to it without restarting the server.

• --epoch-load-concurrency=2: Epochs to load in parallel when starting the RPC server. Defaults to the number of CPUs. This is useful when you have a lot of epochs and want to speed up the initial load time.

• --max-cache=<megabytes>: Memory to use for caching. Defaults to 0 (no limit). This is useful when you want to limit the memory usage of the RPC server.

NOTES:

• By default, the RPC server doesn't support the jsonParsed format. You need to build the RPC server with the make jsonParsed-linux flag to enable this.

Remote vs. local indexes

Indexes can be utilized either over HTTP or via a local file system. Currently, we do not host the indexes on Filecoin, though this may change in the future.

We highly recommend storing indexes locally on high-speed storage for the best performance. The GSFA index required to support getSignaturesForAddress can currently not be used remotely.

If you want to rely on remote indexes, you can leave out the GSFA index or specify the GSFA index to return only the signatures and not the transaction body. In this mode, you can use a remote gSFA index. To enable this mode, run faithful-cli in the following way:

faithful-cli rpc -gsfa-only-signatures=true 455.yml 

Proxying

The RPC server provides a proxy mode that allows it to forward traffic it can't serve to a downstream RPC server. To configure this, provide the command line argument --proxy=/path/to/faithful-proxy-config.jsonpointing it to a config file. The config file should look like this:

{
	"target": "https://api.mainnet-beta.solana.com",
	"headers": {
		"My-Header": "My-Value"
	},
	"proxyFailedRequests": true
}

The proxyFailedRequests flag will make the RPC server proxy not only RPC methods that it doesn't support but also retry requests that failed to be served from the archives (e.g. a getBlock request that failed to be served from the archives because that epoch is unavailable).

Log Levels

You can set the desired log verbosity level by using the -v flag. The levels are from 0 to 5, where 0 is the least verbose and 5 is the most verbose. The default level is 2.

Example:

faithful-cli -v=5 rpc 455.yml