RPC server

Overview

Old Faithful ships with an RPC server that supports gRPC and JSON-RPC. The JSON-RPC API follows the standard Solana RPC API and supports the following methods:

• getBlock

• getTransaction

• getSignaturesForAddress

• getBlockTime

• getGenesisHash (for epoch 0)

• getFirstAvailableBlock

• getSlot

• getVersion

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.

Configuration file format

To configure the RPC server, you create a configuration file per Epoch of data you want the server to support. The RPC server allows you to specify a single file or a folder of config files if you want to support multiple. The RPC server can also be configured to watch this folder for newly added epochs, meaning you can put new ones online.

The basics of the Epoch configuration file contains three fields:

• version: current version is 1

• epoch: the epoch that this config file is for, an Old Faithful server can only host one config per epoch

• genesis: (only used for epoch 0), provide a URI to a genesis file if you want to serve epoch 0.

• data: retrieval configuration for the block/transaction data

  • car: used for Filecoin v1, http, and local file system retrievals

  • filecoin: used for Filecoin v2 retrievals

• indexes: retrieval configuration for the index data (each index header is a uri argument)

  • slot_to_cid: provide a local file system path or HTTP URI to the slot-to-cid index

  • cid_to_offset_and_size: provide a local file system path or HTTP URI to the cid-to-offset-and-size index

  • sig_to_cid: provide a local file system path or HTTP URI to the sig-to-cid index

  • sig_exists: provide a local file system path or HTTP URI to the sig exists index

  • gsfa: provide a local file system path to an unpacked gsfa index folder. If you want to use a remote URI, you need to start the faithful RPC with --gsfa-only-signatures.

Sample config file

epoch: 0 # epoch number (required)
version: 1 # version number (required)
data: # data section (required)
  car:
    # Source the data from a CAR file (car-mode).
    # The URI can be a local filepath or an HTTP url.
    # This makes the indexes.cid_to_offset_and_size required.
    # If you are running in filecoin-mode, you can omit the car section entirely.
    uri: /media/runner/solana/cars/epoch-0.car
  filecoin:
    # filecoin-mode section: source the data directly from filecoin.
    # If you are running in car-mode, you can omit this section.
    # if enable=true, then the data will be sourced from filecoin.
    # if enable=false, then the data will be sourced from a CAR file (see 'car' section above).
    enable: false
genesis: # genesis section (required for epoch 0 only)
  # Local filepath to the genesis tarball.
  # You can download the genesis tarball from
  # wget https://api.mainnet-beta.solana.com/genesis.tar.bz2
  uri: /media/runner/solana/genesis.tar.bz2
indexes: # indexes section (required)
  cid_to_offset_and_size:
    # Required when using a CAR file; you can provide either a local filepath or a HTTP url.
    # Not used when running in filecoin-mode.
    uri: '/media/runner/solana/indexes/epoch-0/epoch-0-bafyreifljyxj55v6jycjf2y7tdibwwwqx75eqf5mn2thip2sswyc536zqq-mainnet-cid-to-offset-and-size.index'
  slot_to_cid:
    # required (always); you can provide either a local filepath or a HTTP url:
    uri: '/media/runner/solana/indexes/epoch-0/epoch-0-bafyreifljyxj55v6jycjf2y7tdibwwwqx75eqf5mn2thip2sswyc536zqq-mainnet-slot-to-cid.index'
  sig_to_cid:
    # required (always); you can provide either a local filepath or a HTTP url:
    uri: '/media/runner/solana/indexes/epoch-0/epoch-0-bafyreifljyxj55v6jycjf2y7tdibwwwqx75eqf5mn2thip2sswyc536zqq-mainnet-sig-to-cid.index'
  sig_exists:
    # required (always); you can provide either a local filepath or a HTTP url:
    uri: '/media/runner/solana/indexes/epoch-0/epoch-0-bafyreifljyxj55v6jycjf2y7tdibwwwqx75eqf5mn2thip2sswyc536zqq-mainnet-sig-exists.index'
  gsfa: # getSignaturesForAddress index
    # optional; must be a local directory path.
    uri: '/media/runner/solana/indexes/epoch-0/gsfa/epoch-0-bafyreifljyxj55v6jycjf2y7tdibwwwqx75eqf5mn2thip2sswyc536zqq-gsfa.indexdir'

Data retrieval modes

The faithful RPC server supports four different data retrieval modes. You can opt for the one that fits your needs the best.

• Local file system

• HTTP (useful for S3 and S3 likes)

• Filecoin v1

• Filecoin v2 (in progress)

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